@oh-my-pi/pi-coding-agent 17.2.4 → 17.2.6

package/src/cli/help-extra.ts

@@ -0,0 +1,89 @@
+import "@oh-my-pi/pi-utils/env";
+import { APP_NAME, CONFIG_DIR_NAME } from "@oh-my-pi/pi-utils/dirs";
+import chalk from "chalk";
+
+export function getExtraHelpText(): string {
+	return `${chalk.bold("Environment Variables:")}
+  ${chalk.dim("# Core Providers")}
+  ANTHROPIC_API_KEY          - Anthropic Claude models
+  ANTHROPIC_OAUTH_TOKEN      - Anthropic OAuth (takes precedence over API key)
+  CLAUDE_CODE_USE_FOUNDRY    - Enable Anthropic Foundry mode (uses Foundry endpoint + mTLS)
+  FOUNDRY_BASE_URL           - Anthropic Foundry base URL (e.g., https://<foundry-host>)
+  ANTHROPIC_FOUNDRY_API_KEY  - Anthropic token used as Authorization: Bearer <token> in Foundry mode
+  ANTHROPIC_CUSTOM_HEADERS   - Extra headers for Foundry or any custom ANTHROPIC_BASE_URL gateway (e.g., "user-id: USERNAME")
+  CLAUDE_CODE_CLIENT_CERT    - Client certificate (PEM path or inline PEM) for mTLS
+  CLAUDE_CODE_CLIENT_KEY     - Client private key (PEM path or inline PEM) for mTLS
+  NODE_EXTRA_CA_CERTS        - CA bundle path (or inline PEM) for server certificate validation
+  OPENAI_API_KEY             - OpenAI GPT models
+  GEMINI_API_KEY             - Google Gemini models
+  COPILOT_GITHUB_TOKEN      - GitHub Copilot
+
+  ${chalk.dim("# Additional LLM Providers")}
+  AZURE_OPENAI_API_KEY       - Azure OpenAI models
+  GROQ_API_KEY               - Groq models
+  CEREBRAS_API_KEY           - Cerebras models
+  XAI_API_KEY                - xAI Grok models
+  OPENROUTER_API_KEY         - OpenRouter aggregated models
+  KILO_API_KEY               - Kilo Gateway models
+  MISTRAL_API_KEY            - Mistral models
+  ZAI_API_KEY                - z.ai models (ZhipuAI/GLM)
+  UMANS_AI_CODING_PLAN_API_KEY - Umans AI Coding Plan models
+  UMANS_WEBSEARCH_PROVIDER    - Umans gateway web search backend (native or exa)
+  MINIMAX_API_KEY            - MiniMax models
+  OPENCODE_API_KEY           - OpenCode Zen/OpenCode Go models
+  CURSOR_ACCESS_TOKEN        - Cursor AI models
+  AI_GATEWAY_API_KEY         - Vercel AI Gateway
+  WAFER_SERVERLESS_API_KEY   - Wafer Serverless (pay-as-you-go)
+
+  ${chalk.dim("# Cloud Providers")}
+  AWS_PROFILE                - AWS Bedrock (or AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
+  GOOGLE_CLOUD_PROJECT       - Google Vertex AI (requires GOOGLE_CLOUD_LOCATION)
+  GOOGLE_APPLICATION_CREDENTIALS - Service account for Vertex AI
+
+  ${chalk.dim("# Search & Tools")}
+  EXA_API_KEY                - Exa web search
+  BRAVE_API_KEY              - Brave web search
+  PERPLEXITY_API_KEY         - Perplexity web search API key (optional; anonymous fallback)
+  PERPLEXITY_COOKIES         - Perplexity web search (session cookie)
+  TAVILY_API_KEY             - Tavily web search
+  TINYFISH_API_KEY           - TinyFish web search
+  FIRECRAWL_API_KEY          - Firecrawl web search
+  ANTHROPIC_SEARCH_API_KEY   - Anthropic web search (override; isolates search from main ANTHROPIC_API_KEY)
+  ANTHROPIC_SEARCH_BASE_URL  - Anthropic web search base URL (override; pairs with ANTHROPIC_SEARCH_API_KEY)
+
+  ${chalk.dim("# Configuration")}
+  OMP_PROFILE                 - Named profile for isolated agent state (same as --profile)
+  Use \`omp --profile <name> --alias <command>\` to create a shell shortcut for a profile
+  PI_CODING_AGENT_DIR        - Session storage directory (default: ~/${CONFIG_DIR_NAME}/agent)
+  PI_PACKAGE_DIR             - Override package directory (for Nix/Guix store paths)
+  PI_SMOL_MODEL              - Override smol/fast model (see --smol)
+  PI_SLOW_MODEL              - Override slow/reasoning model (see --slow)
+  PI_PLAN_MODEL              - Override planning model (see --plan)
+  PI_NO_PTY                  - Disable PTY-based interactive bash execution
+  For complete environment variable reference, see:
+  ${chalk.dim("docs/environment-variables.md")}
+${chalk.bold("Available Tools (default-enabled unless noted):")}
+  read          - Read file contents
+  bash          - Execute bash commands
+  edit          - Edit files with find/replace
+  write         - Write files (creates/overwrites)
+  grep          - Search file contents
+  glob          - Find files by glob pattern
+  lsp           - Language server protocol (code intelligence)
+  python        - Execute Python code (requires: ${APP_NAME} setup python)
+  notebook      - Edit Jupyter notebooks
+  inspect_image - Analyze images with a vision model
+  browser       - Browser automation (Puppeteer)
+  computer      - Native host desktop capture and input (disabled by default)
+  task          - Launch sub-agents for parallel tasks
+  todo          - Manage todo/task lists
+  web_search    - Search the web
+  ask           - Ask user questions (interactive mode only)
+
+${chalk.bold("Plugin Options:")}
+  --plugin-dir <path>        Load plugin from directory (repeatable)
+
+${chalk.bold("Useful Commands:")}
+  omp agents unpack           - Export bundled subagents to ~/.omp/agent/agents (default)
+  omp agents unpack --project - Export bundled subagents to ./.omp/agents`;
+}

package/src/cli/setup-cli.ts

@@ -4,10 +4,10 @@
  * Handles `omp setup` for onboarding and `omp setup <component>` for optional dependencies.
  */
 import * as path from "node:path";
-import { $which, APP_NAME, getProjectDir, getPythonEnvDir } from "@oh-my-pi/pi-utils";
-import { $ } from "bun";
+import { APP_NAME, getProjectDir, getPythonEnvDir } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
 import { Settings, settings } from "../config/settings";
+import { checkPythonKernelAvailability } from "../eval/py/kernel";
 import { theme } from "../modes/theme/theme";
 import { downloadSttModel, isSttModelCached } from "../stt/downloader";
 import { isSttModelKey, STT_MODEL_OPTIONS } from "../stt/models";
@@ -82,25 +82,14 @@ function managedPythonPath(): string {
 /**
  * Check Python environment and kernel dependencies.
  */
-async function checkPythonSetup(): Promise<PythonCheckResult> {
-	const result: PythonCheckResult = {
-		available: false,
+async function checkPythonSetup(cwd: string, interpreter?: string): Promise<PythonCheckResult> {
+	const availability = await checkPythonKernelAvailability(cwd, interpreter, { forceProbe: true });
+	return {
+		available: availability.ok,
+		pythonPath: availability.pythonPath,
+		usingManagedEnv: availability.pythonPath === managedPythonPath(),
 		managedEnvPath: MANAGED_PYTHON_ENV,
 	};
-
-	const systemPythonPath = $which("python") ?? $which("python3");
-	const managedPath = managedPythonPath();
-	const hasManagedEnv = await Bun.file(managedPath).exists();
-
-	const pythonPath = systemPythonPath ?? (hasManagedEnv ? managedPath : undefined);
-	if (!pythonPath) {
-		return result;
-	}
-	const probe = await $`${pythonPath} -c "import sys;sys.exit(0)"`.quiet().nothrow();
-	result.pythonPath = pythonPath;
-	result.available = probe.exitCode === 0;
-	result.usingManagedEnv = pythonPath === managedPath;
-	return result;
 }
 
 /**
@@ -126,7 +115,10 @@ export async function runSetupCommand(cmd: SetupCommandArgs): Promise<void> {
 }
 
 async function handlePythonSetup(flags: { json?: boolean; check?: boolean }): Promise<void> {
-	const check = await checkPythonSetup();
+	const cwd = getProjectDir();
+	const projectSettings = await Settings.init({ cwd });
+	const interpreter = projectSettings.get("python.interpreter")?.trim() || undefined;
+	const check = await checkPythonSetup(cwd, interpreter);
 
 	if (flags.json) {
 		console.log(JSON.stringify(check, null, 2));
@@ -136,7 +128,7 @@ async function handlePythonSetup(flags: { json?: boolean; check?: boolean }): Pr
 
 	if (!check.pythonPath) {
 		console.error(chalk.red(`${theme.status.error} Python not found`));
-		console.error(chalk.dim("Install Python 3.8+ and ensure it's in your PATH"));
+		console.error(chalk.dim("Install Python 3.8+ or set python.interpreter to its executable path"));
 		process.exit(1);
 	}
 

package/src/cli/thinking-levels.ts

@@ -0,0 +1,7 @@
+import { THINKING_EFFORTS } from "@oh-my-pi/pi-catalog/effort";
+
+/**
+ * Thinking selectors accepted by the `--thinking` CLI flag, in display order.
+ * Shared by help metadata, shell completions, and validation warnings.
+ */
+export const CLI_THINKING_LEVELS: readonly string[] = ["off", ...THINKING_EFFORTS, "auto"];

package/src/cli/update-cli.ts

@@ -765,14 +765,33 @@ async function pruneBunCacheAfterGlobalInstall(): Promise<BunInstallCachePruneRe
 /**
  * Detect a musl-libc Linux host (Alpine, Void-musl) so self-update replaces a
  * musl binary with the musl release asset instead of the glibc build, which
- * would fail to start on the next run. Mirrors the detection in
- * scripts/install.sh.
+ * would fail to start on the next run. The loader file alone is not sufficient:
+ * glibc hosts may have musl installed for cross-compilation.
  */
-function isMuslLinux(): boolean {
-	if (process.platform !== "linux") return false;
-	if (fs.existsSync("/etc/alpine-release")) return true;
-	const loaderArch = process.arch === "arm64" ? "aarch64" : "x86_64";
-	return fs.existsSync(`/lib/ld-musl-${loaderArch}.so.1`);
+interface MuslDetectionOptions {
+	platform?: NodeJS.Platform;
+	alpineRelease?: boolean;
+	lddOutput?: string;
+}
+
+function detectLddOutput(): string | undefined {
+	try {
+		const result = Bun.spawnSync(["ldd", "--version"], { stdout: "pipe", stderr: "pipe" });
+		return `${result.stdout.toString("utf-8")}\n${result.stderr.toString("utf-8")}`;
+	} catch {
+		return undefined;
+	}
+}
+
+function isMuslLinux(options: MuslDetectionOptions = {}): boolean {
+	if ((options.platform ?? process.platform) !== "linux") return false;
+	if (options.alpineRelease ?? fs.existsSync("/etc/alpine-release")) return true;
+	return /\bmusl\b/i.test(options.lddOutput ?? detectLddOutput() ?? "");
+}
+
+/** Test seam for libc detection. */
+export function isMuslLinuxForTest(options: Required<MuslDetectionOptions>): boolean {
+	return isMuslLinux(options);
 }
 
 /**

package/src/cli-commands.ts

@@ -9,42 +9,179 @@
  * regression that motivated the split.
  */
 import type { CommandEntry } from "@oh-my-pi/pi-utils/cli";
+import * as commandHelp from "./cli/command-help";
 import { flagConsumesValue } from "./cli/flag-tables";
+import { launchHelp } from "./commands/launch-help";
 
 export const commands: CommandEntry[] = [
-	{ name: "launch", load: () => import("./commands/launch").then(m => m.default) },
-	{ name: "acp", load: () => import("./commands/acp").then(m => m.default) },
-	{ name: "auth-broker", load: () => import("./commands/auth-broker").then(m => m.default) },
-	{ name: "auth-gateway", load: () => import("./commands/auth-gateway").then(m => m.default) },
-	{ name: "agents", load: () => import("./commands/agents").then(m => m.default) },
-	{ name: "bench", load: () => import("./commands/bench").then(m => m.default) },
-	{ name: "cleanse", load: () => import("./commands/cleanse").then(m => m.default) },
-	{ name: "commit", load: () => import("./commands/commit").then(m => m.default) },
-	{ name: "completions", load: () => import("./commands/completions").then(m => m.default) },
-	{ name: "__complete", load: () => import("./commands/complete").then(m => m.default) },
-	{ name: "config", load: () => import("./commands/config").then(m => m.default) },
-	{ name: "dry-balance", load: () => import("./commands/dry-balance").then(m => m.default) },
-	{ name: "gc", load: () => import("./commands/gc").then(m => m.default) },
-	{ name: "grep", load: () => import("./commands/grep").then(m => m.default) },
-	{ name: "gallery", load: () => import("./commands/gallery").then(m => m.default) },
-	{ name: "grievances", load: () => import("./commands/grievances").then(m => m.default) },
-	{ name: "install", load: () => import("./commands/install").then(m => m.default) },
-	{ name: "join", load: () => import("./commands/join").then(m => m.default) },
-	{ name: "models", load: () => import("./commands/models").then(m => m.default) },
-	{ name: "plugin", load: () => import("./commands/plugin").then(m => m.default) },
-	{ name: "say", load: () => import("./commands/say").then(m => m.default) },
-	{ name: "setup", load: () => import("./commands/setup").then(m => m.default) },
-	{ name: "shell", load: () => import("./commands/shell").then(m => m.default) },
-	{ name: "read", load: () => import("./commands/read").then(m => m.default) },
-	{ name: "ssh", load: () => import("./commands/ssh").then(m => m.default) },
-	{ name: "stats", load: () => import("./commands/stats").then(m => m.default) },
-	{ name: "update", load: () => import("./commands/update").then(m => m.default) },
-	{ name: "usage", load: () => import("./commands/usage").then(m => m.default) },
-	{ name: "tiny-models", load: () => import("./commands/tiny-models").then(m => m.default) },
-	{ name: "token", load: () => import("./commands/token").then(m => m.default) },
-	{ name: "ttsr", load: () => import("./commands/ttsr").then(m => m.default) },
-	{ name: "worktree", load: () => import("./commands/worktree").then(m => m.default), aliases: ["wt"] },
-	{ name: "search", load: () => import("./commands/web-search").then(m => m.default), aliases: ["q"] },
+	{ name: "launch", load: () => import("./commands/launch").then(m => m.default), help: launchHelp },
+	{
+		name: "acp",
+		load: () => import("./commands/acp").then(m => m.default),
+		help: commandHelp.acpHelp,
+	},
+	{
+		name: "auth-broker",
+		load: () => import("./commands/auth-broker").then(m => m.default),
+		help: commandHelp.authBrokerHelp,
+	},
+	{
+		name: "auth-gateway",
+		load: () => import("./commands/auth-gateway").then(m => m.default),
+		help: commandHelp.authGatewayHelp,
+	},
+	{
+		name: "agents",
+		load: () => import("./commands/agents").then(m => m.default),
+		help: commandHelp.agentsHelp,
+	},
+	{
+		name: "bench",
+		load: () => import("./commands/bench").then(m => m.default),
+		help: commandHelp.benchHelp,
+	},
+	{
+		name: "browser-relay",
+		load: () => import("./commands/browser-relay").then(m => m.default),
+		help: commandHelp.browserRelayHelp,
+	},
+	{
+		name: "cleanse",
+		load: () => import("./commands/cleanse").then(m => m.default),
+		help: commandHelp.cleanseHelp,
+	},
+	{
+		name: "commit",
+		load: () => import("./commands/commit").then(m => m.default),
+		help: commandHelp.commitHelp,
+	},
+	{
+		name: "completions",
+		load: () => import("./commands/completions").then(m => m.default),
+		help: commandHelp.completionsHelp,
+	},
+	{
+		name: "__complete",
+		load: () => import("./commands/complete").then(m => m.default),
+		help: commandHelp.completeHelp,
+	},
+	{
+		name: "config",
+		load: () => import("./commands/config").then(m => m.default),
+		help: commandHelp.configHelp,
+	},
+	{
+		name: "dry-balance",
+		load: () => import("./commands/dry-balance").then(m => m.default),
+		help: commandHelp.dryBalanceHelp,
+	},
+	{
+		name: "gc",
+		load: () => import("./commands/gc").then(m => m.default),
+		help: commandHelp.gcHelp,
+	},
+	{
+		name: "grep",
+		load: () => import("./commands/grep").then(m => m.default),
+		help: commandHelp.grepHelp,
+	},
+	{
+		name: "gallery",
+		load: () => import("./commands/gallery").then(m => m.default),
+		help: commandHelp.galleryHelp,
+	},
+	{
+		name: "grievances",
+		load: () => import("./commands/grievances").then(m => m.default),
+		help: commandHelp.grievancesHelp,
+	},
+	{
+		name: "install",
+		load: () => import("./commands/install").then(m => m.default),
+		help: commandHelp.installHelp,
+	},
+	{
+		name: "join",
+		load: () => import("./commands/join").then(m => m.default),
+		help: commandHelp.joinHelp,
+	},
+	{
+		name: "models",
+		load: () => import("./commands/models").then(m => m.default),
+		help: commandHelp.modelsHelp,
+	},
+	{
+		name: "plugin",
+		load: () => import("./commands/plugin").then(m => m.default),
+		help: commandHelp.pluginHelp,
+	},
+	{
+		name: "say",
+		load: () => import("./commands/say").then(m => m.default),
+		help: commandHelp.sayHelp,
+	},
+	{
+		name: "setup",
+		load: () => import("./commands/setup").then(m => m.default),
+		help: commandHelp.setupHelp,
+	},
+	{
+		name: "shell",
+		load: () => import("./commands/shell").then(m => m.default),
+		help: commandHelp.shellHelp,
+	},
+	{
+		name: "read",
+		load: () => import("./commands/read").then(m => m.default),
+		help: commandHelp.readHelp,
+	},
+	{
+		name: "ssh",
+		load: () => import("./commands/ssh").then(m => m.default),
+		help: commandHelp.sshHelp,
+	},
+	{
+		name: "stats",
+		load: () => import("./commands/stats").then(m => m.default),
+		help: commandHelp.statsHelp,
+	},
+	{
+		name: "update",
+		load: () => import("./commands/update").then(m => m.default),
+		help: commandHelp.updateHelp,
+	},
+	{
+		name: "usage",
+		load: () => import("./commands/usage").then(m => m.default),
+		help: commandHelp.usageHelp,
+	},
+	{
+		name: "tiny-models",
+		load: () => import("./commands/tiny-models").then(m => m.default),
+		help: commandHelp.tinyModelsHelp,
+	},
+	{
+		name: "token",
+		load: () => import("./commands/token").then(m => m.default),
+		help: commandHelp.tokenHelp,
+	},
+	{
+		name: "ttsr",
+		load: () => import("./commands/ttsr").then(m => m.default),
+		help: commandHelp.ttsrHelp,
+	},
+	{
+		name: "worktree",
+		load: () => import("./commands/worktree").then(m => m.default),
+		aliases: ["wt"],
+		help: commandHelp.worktreeHelp,
+	},
+	{
+		name: "search",
+		load: () => import("./commands/web-search").then(m => m.default),
+		aliases: ["q"],
+		help: commandHelp.searchHelp,
+	},
 ];
 
 // Documented-looking plugin/marketplace verbs that are NOT registered top-level

package/src/cli.ts

@@ -15,7 +15,7 @@ try {
  * lightweight CLI runner from pi-utils.
  */
 import { parentPort } from "node:worker_threads";
-import type { CliConfig } from "@oh-my-pi/pi-utils/cli";
+import type { CliConfig, CommandMetadata } from "@oh-my-pi/pi-utils/cli";
 import {
 	APP_NAME,
 	getActiveProfile,
@@ -33,6 +33,7 @@ import { startJsEvalProcess } from "./eval/js/process-entry";
 import type { WorkerInbound as JsWorkerInbound, WorkerOutbound as JsWorkerOutbound } from "./eval/js/worker-protocol";
 import { DAEMON_BROKER_WORKER_ARG } from "./launch/protocol";
 import { TERMINAL_OUTPUT_WORKER_ARG } from "./launch/terminal-output-worker-protocol";
+import { LSP_MUX_WORKER_ARG } from "./lsp/mux/protocol";
 import { COMPUTER_WORKER_ARG } from "./tools/computer/protocol";
 import { smokeTestComputerWorker } from "./tools/computer/supervisor";
 import { startComputerWorker } from "./tools/computer/worker-entry";
@@ -60,9 +61,13 @@ const isProcessEntry = import.meta.main || process.env.PI_COMPILED === "true";
 // `@oh-my-pi/pi-utils/env` eagerly loads `.env` from the agent directory at
 // import time, so it must not be imported before `setProfile` runs.
 
-async function showHelp(config: CliConfig): Promise<void> {
-	const { renderRootHelp } = await import("@oh-my-pi/pi-utils/cli");
-	const { getExtraHelpText } = await import("./cli/args");
+async function showHelp(config: CliConfig<CommandMetadata>): Promise<void> {
+	// Root help historically loads the selected profile's environment. The
+	// lazily loaded help module imports it statically after profile bootstrap.
+	const [{ renderRootHelp }, { getExtraHelpText }] = await Promise.all([
+		import("@oh-my-pi/pi-utils/cli"),
+		import("./cli/help-extra"),
+	]);
 	renderRootHelp(config);
 	const extra = getExtraHelpText();
 	if (extra.trim().length > 0) {
@@ -89,6 +94,7 @@ async function runSmokeTest(): Promise<void> {
 	const { smokeTestJsEvalWorker } = await import("./eval/js/context-manager");
 	// Other smoke dependencies stay lazy so normal CLI startup does not load their worker clients.
 	const { smokeTestDaemonBroker } = await import("./launch/client");
+	const { smokeTestLspMux } = await import("./lsp/mux/daemon");
 	const { smokeTestTerminalOutputWorker } = await import("./launch/terminal-output-worker-client");
 	await smokeTestSyncWorker();
 
@@ -111,6 +117,7 @@ async function runSmokeTest(): Promise<void> {
 	await smokeTestTtsWorker();
 	await smokeTestMnemopiEmbedWorker();
 	await smokeTestDaemonBroker();
+	await smokeTestLspMux();
 	await smokeTestTerminalOutputWorker();
 	process.stdout.write("smoke-test: ok\n");
 }
@@ -210,6 +217,11 @@ async function runWorkerEntrypoint(arg: string | undefined): Promise<boolean> {
 		await startDaemonBrokerFromEnvironment();
 		return true;
 	}
+	if (arg === LSP_MUX_WORKER_ARG) {
+		const { startLspMuxFromEnvironment } = await import("./lsp/mux/server");
+		await startLspMuxFromEnvironment();
+		return true;
+	}
 	return false;
 }
 
@@ -397,7 +409,7 @@ export async function runCli(argv: string[]): Promise<void> {
 		process.exitCode = 1;
 		return;
 	}
-	return run({ bin: APP_NAME, version: VERSION, argv: resolved.argv, commands, help: showHelp });
+	return run({ bin: APP_NAME, version: VERSION, argv: resolved.argv, commands, metadataHelp: showHelp });
 }
 
 // Floating call instead of top-level await: TLA forces `--bytecode` (CJS

package/src/commands/acp.ts

@@ -4,13 +4,15 @@
  * Thin wrapper around the launch flow that forces `mode: "acp"` unless the
  * ACP terminal-auth flag asks the same command to open the interactive TUI.
  */
+
 import { Command } from "@oh-my-pi/pi-utils/cli";
 import { type Args as ParsedArgs, parseArgs, reportCliUsageError } from "../cli/args";
+import { acpHelp as commandHelp } from "../cli/command-help";
 import { runRootCommand } from "../main";
 import { prepareAcpTerminalAuthArgs } from "../modes/acp/terminal-auth";
 
 export default class Acp extends Command {
-	static description = "Run Oh My Pi as an ACP (Agent Client Protocol) server over stdio";
+	static description = commandHelp.description;
 	static strict = false;
 
 	async run(): Promise<void> {

package/src/commands/agents.ts

@@ -1,15 +1,16 @@
 /**
  * Manage bundled task agents.
  */
+
 import { Args, Command, Flags, renderCommandHelp } from "@oh-my-pi/pi-utils/cli";
 import { type AgentsAction, type AgentsCommandArgs, runAgentsCommand } from "../cli/agents-cli";
+import { agentsHelp as commandHelp } from "../cli/command-help";
 import { initTheme } from "../modes/theme/theme";
 
 const ACTIONS: AgentsAction[] = ["unpack"];
 
 export default class Agents extends Command {
-	static description = "Manage bundled task agents";
-
+	static description = commandHelp.description;
 	static args = {
 		action: Args.string({
 			description: "Agents action",

package/src/commands/auth-broker.ts

@@ -1,6 +1,7 @@
 /**
  * `omp auth-broker` — manage the omp credential vault.
  */
+
 import { Args, Command, Flags, renderCommandHelp } from "@oh-my-pi/pi-utils/cli";
 import {
 	AUTH_BROKER_ACTIONS,
@@ -8,11 +9,11 @@ import {
 	type AuthBrokerCommandArgs,
 	runAuthBrokerCommand,
 } from "../cli/auth-broker-cli";
+import { authBrokerHelp as commandHelp } from "../cli/command-help";
 import { initTheme } from "../modes/theme/theme";
 
 export default class AuthBroker extends Command {
-	static description = "Manage the omp auth-broker (credential vault)";
-
+	static description = commandHelp.description;
 	static args = {
 		action: Args.string({
 			description: "Sub-command",

package/src/commands/auth-gateway.ts

@@ -1,6 +1,7 @@
 /**
  * `omp auth-gateway` — run a forward proxy that injects auth from the broker.
  */
+
 import { Args, Command, Flags, renderCommandHelp } from "@oh-my-pi/pi-utils/cli";
 import {
 	AUTH_GATEWAY_ACTIONS,
@@ -8,11 +9,11 @@ import {
 	type AuthGatewayCommandArgs,
 	runAuthGatewayCommand,
 } from "../cli/auth-gateway-cli";
+import { authGatewayHelp as commandHelp } from "../cli/command-help";
 import { initTheme } from "../modes/theme/theme";
 
 export default class AuthGateway extends Command {
-	static description = "Run an auth-gateway forward proxy backed by the configured broker";
-
+	static description = commandHelp.description;
 	static args = {
 		action: Args.string({
 			description: "Sub-command",

package/src/commands/bench.ts

@@ -1,11 +1,10 @@
 import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
 import { runBenchCommand } from "../cli/bench-cli";
+import { benchHelp as commandHelp } from "../cli/command-help";
 import { SERVICE_TIER_OPENAI_VALUES } from "../config/service-tier";
 
 export default class Bench extends Command {
-	static description =
-		"Benchmark models with the same prompt: time-to-first-token and generation throughput (tokens/s)";
-
+	static description = commandHelp.description;
 	static args = {
 		models: Args.string({
 			description: "Model selectors (provider/model or fuzzy id, e.g. opus)",

package/src/commands/browser-relay.ts

@@ -0,0 +1,53 @@
+/**
+ * `omp browser-relay` — drive the user's own Chrome tabs.
+ */
+import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import {
+	BROWSER_RELAY_ACTIONS,
+	type BrowserRelayAction,
+	DEFAULT_RELAY_PORT,
+	runBrowserRelayCommand,
+} from "../cli/browser-relay-cli";
+
+export default class BrowserRelay extends Command {
+	static description = "Run the local CDP relay that lets the browser tool drive your own Chrome tabs";
+
+	static args = {
+		action: Args.string({
+			description: `Action: ${BROWSER_RELAY_ACTIONS.join(" | ")} (default serve)`,
+			options: [...BROWSER_RELAY_ACTIONS],
+			required: false,
+		}),
+	};
+
+	static flags = {
+		port: Flags.integer({ char: "p", description: "Port to listen on", default: DEFAULT_RELAY_PORT }),
+		token: Flags.string({ description: "Require the extension to present this token" }),
+		dir: Flags.string({
+			description: "Extension install directory (install; default ~/.omp/browser-relay/extension)",
+		}),
+		"no-group": Flags.boolean({
+			description: "Don't gather controllable tabs into an 'omp' tab group",
+			default: false,
+		}),
+		verbose: Flags.boolean({ char: "v", description: "Log relay traffic summaries to stderr", default: false }),
+	};
+
+	static examples = [
+		"omp browser-relay install    # write the Chrome extension to disk + setup steps",
+		"omp browser-relay            # serve the relay on the default port",
+		"omp browser-relay -p 9333 --token s3cret",
+	];
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(BrowserRelay);
+		await runBrowserRelayCommand({
+			action: (args.action as BrowserRelayAction | undefined) ?? "serve",
+			port: flags.port,
+			token: flags.token,
+			dir: flags.dir,
+			group: !flags["no-group"],
+			verbose: flags.verbose,
+		});
+	}
+}

package/src/commands/cleanse.ts

@@ -1,11 +1,11 @@
 import { postmortem } from "@oh-my-pi/pi-utils";
 import { Command, Flags } from "@oh-my-pi/pi-utils/cli";
 import { runCleanseCommand } from "../cleanse";
+import { cleanseHelp as commandHelp } from "../cli/command-help";
 import { CliUsageError } from "../cli/usage-error";
 
 export default class Cleanse extends Command {
-	static description = "Detect and fix project diagnostics with weighted parallel subagents";
-
+	static description = commandHelp.description;
 	static flags = {
 		agents: Flags.integer({
 			char: "n",