A self-improving RLM agent for coding workflows and long-running autonomous tasks.
Rust
fix(coding-agent): simplify top-level help (ENG-4688) (#455)
kt8bf2164f7999
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.mdindex e5ba0e55e3..223ff79a54 100644--- a/packages/coding-agent/CHANGELOG.md+++ b/packages/coding-agent/CHANGELOG.md@@ -2,6 +2,7 @@## [Unreleased]+- Changed top-level CLI help to show concise common options and commands without loading runtime resources ([ENG-4688](https://linear.app/primeintellect/issue/ENG-4688/help-command-is-obscenely-verbose)).- Fixed completed subagents cancelling their RLM heartbeats before the first run ([ENG-4652](https://linear.app/primeintellect/issue/ENG-4652/subagent-heartbeats-dont-work)).- Changed the fullscreen follow shortcut from `Alt+Down` to `Ctrl+Shift+Down` for more reliable terminal input ([ENG-4684](https://linear.app/primeintellect/issue/ENG-4684/altdown-doesnt-work)).- Fixed active heartbeats not resuming after Prime Agent updates ([ENG-4657](https://linear.app/primeintellect/issue/ENG-4657/heartbeats-dont-survive-updatesdaemon-reboots)).diff --git a/packages/coding-agent/docs/usage.md b/packages/coding-agent/docs/usage.mdindex b7b577eb3b..999734533d 100644--- a/packages/coding-agent/docs/usage.md+++ b/packages/coding-agent/docs/usage.md@@ -173,7 +173,7 @@ cat README.md | pi -p "Summarize this text"| `--provider <name>` | Provider, such as `anthropic`, `openai`, or `google` || `--model <pattern>` | Model pattern or ID; supports `provider/id` and optional `:<thinking>` || `--api-key <key>` | API key, overriding environment variables |-| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |+| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` || `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |Use `prime-agent model list [search]` to list available models.@@ -205,11 +205,11 @@ Built-in tools: `ipython`.| Option | Description ||--------|-------------|| `-e`, `--extension <source>` | Load an extension from path, npm, or git; repeatable |-| `--no-extensions` | Disable extension discovery |+| `--no-extensions`, `-ne` | Disable extension discovery || `--skill <path>` | Load a skill; repeatable |-| `--no-skills` | Disable skill discovery |+| `--no-skills`, `-ns` | Disable skill discovery || `--prompt-template <path>` | Load a prompt template; repeatable |-| `--no-prompt-templates` | Disable prompt template discovery |+| `--no-prompt-templates`, `-np` | Disable prompt template discovery || `--theme <path>` | Load a theme; repeatable || `--no-themes` | Disable theme discovery || `--no-context-files`, `-nc` | Disable `AGENTS.md` and `CLAUDE.md` discovery |@@ -220,15 +220,31 @@ Combine `--no-*` with explicit flags to load exactly what you need, ignoring setpi --no-extensions -e ./my-extension.ts```+### Autonomous Options++| Option | Description |+|--------|-------------|+| `--autonomous` | Continue until host-observable terminal evidence exists |+| `--autonomous-gate <command>` | Run a command before autonomous mode may finish; repeatable |+| `--autonomous-gate-retries <n>` | Maximum retries for each failed gate; default is 3 |+| `--autonomous-gate-timeout-ms <n>` | Timeout for each gate command |+| `--autonomous-max-continuations <n>` | Maximum autonomous follow-up messages; default is 3 |+| `--autonomous-max-turns <n>` | Maximum assistant turns; default is 12 |+| `--autonomous-max-tokens <n>` | Maximum tokens; default is 80000 |+| `--autonomous-timeout-ms <n>` | Maximum wall-clock duration; default is 1800000 milliseconds |+### Other Options| Option | Description ||--------|-------------|+| `--cwd <dir>` | Use a specific working directory for the session || `--system-prompt <text>` | Replace default prompt; context files and skills are still appended || `--append-system-prompt <text>` | Append to system prompt || `--verbose` | Force verbose startup |+| `--offline` | Disable startup network operations || `-h`, `--help` | Show help || `-v`, `--version` | Show version |+| `--` | End option parsing and treat all following arguments as messages |### File Argumentsdiff --git a/packages/coding-agent/src/cli/args.ts b/packages/coding-agent/src/cli/args.tsindex 05583c5d75..a9499f56c2 100644--- a/packages/coding-agent/src/cli/args.ts+++ b/packages/coding-agent/src/cli/args.ts@@ -3,10 +3,7 @@*/import type { ThinkingLevel } from "@earendil-works/pi-agent-core";-import chalk from "chalk";-import { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR, ENV_SESSION_DIR } from "../config.js";-import type { ExtensionFlag } from "../core/extensions/types.js";-import { formatTopLevelHelp } from "./command-registry.js";+import { APP_NAME } from "../config.js";export type Mode = "text" | "json" | "rpc" | "daemon";@@ -311,168 +308,6 @@ export function parseArgs(args: string[]): Args {return result;}-export function printHelp(extensionFlags?: ExtensionFlag[]): void {- const extensionFlagsText =- extensionFlags && extensionFlags.length > 0- ? `\n${chalk.bold("Extension CLI Flags:")}\n${extensionFlags- .map((flag) => {- const value = flag.type === "string" ? " <value>" : "";- const description = flag.description ?? `Registered by ${flag.extensionPath}`;- return ` --${flag.name}${value}`.padEnd(30) + description;- })- .join("\n")}\n`- : "";- console.log(`${formatTopLevelHelp()}--${chalk.bold("Options:")}- --provider <name> Provider name (default: google)- --model <pattern> Model pattern or ID (supports "provider/id" and optional ":<thinking>")- --api-key <key> API key (defaults to env vars)- --cwd <dir> Working directory for the session- --system-prompt <text> System prompt (default: coding assistant prompt)- --append-system-prompt <text> Append text or file contents to the system prompt (can be used multiple times)- --mode <mode> Output mode: text (default), json, or rpc- --print, -p Non-interactive mode: process prompt and exit- --continue, -c Continue previous session- --resume, -r [path|id] Resume specific session, or browse when omitted- --fork <path|id> Fork specific session file or partial UUID into a new session- --session-dir <dir> Directory for session storage and lookup- --no-session Don't save session (ephemeral)- --models <patterns> Comma-separated model patterns for Ctrl+P cycling- Supports globs (anthropic/*, *sonnet*) and fuzzy matching- --no-tools, -nt Disable all tools by default (built-in and extension)- --no-builtin-tools, -nbt Disable built-in tools by default but keep extension/custom tools enabled- --tools, -t <tools> Comma-separated allowlist of tool names to enable- Applies to built-in, extension, and custom tools- --thinking <level> Set thinking level: off, minimal, low, medium, high, xhigh, max- --extension, -e <path> Load an extension file (can be used multiple times)- --no-extensions, -ne Disable extension discovery (explicit -e paths still work)- --skill <path> Load a skill file or directory (can be used multiple times)- --no-skills, -ns Disable skills discovery and loading- --prompt-template <path> Load a prompt template file or directory (can be used multiple times)- --no-prompt-templates, -np Disable prompt template discovery and loading- --theme <path> Load a theme file or directory (can be used multiple times)- --no-themes Disable theme discovery and loading- --no-context-files, -nc Disable AGENTS.md and CLAUDE.md discovery and loading- --autonomous Continue autonomously until host-observable terminal evidence exists- --autonomous-gate <command> Run a command before autonomous mode may finish (repeatable)- --autonomous-gate-retries <n> Max autonomous retries per failed gate (default: 3)- --autonomous-gate-timeout-ms <n> Timeout per autonomous gate command in milliseconds- --autonomous-max-continuations <n> Max autonomous follow-up messages (default: 3)- --autonomous-max-turns <n> Max assistant turns while autonomous mode is active (default: 12)- --autonomous-max-tokens <n> Max tokens while autonomous mode is active (default: 80000)- --autonomous-timeout-ms <n> Max autonomous wall-clock time in milliseconds (default: 1800000)- --verbose Force verbose startup (overrides quietStartup setting)- --offline Disable startup network operations (same as PI_OFFLINE=1)- --help, -h Show this help- --version, -v Show version number- -- End of options; treat all following args as messages--Extensions can register additional flags (e.g., --plan from plan-mode extension).${extensionFlagsText}--${chalk.bold("Examples:")}- # Interactive mode- ${APP_NAME}-- # Interactive mode with initial prompt- ${APP_NAME} "List all .ts files in src/"-- # Include files in initial message- ${APP_NAME} @prompt.md @image.png "What color is the sky?"-- # Non-interactive mode (process and exit)- ${APP_NAME} -p "List all .ts files in src/"-- # Multiple messages (interactive)- ${APP_NAME} "Read package.json" "What dependencies do we have?"-- # Prompt that starts with a dash (use -- to end option parsing)- ${APP_NAME} -- "- You are given a state dictionary..."-- # Continue previous session- ${APP_NAME} --continue "What did we discuss?"-- # Use different model- ${APP_NAME} --provider openai --model gpt-4o-mini "Help me refactor this code"-- # Use model with provider prefix (no --provider needed)- ${APP_NAME} --model openai/gpt-4o "Help me refactor this code"-- # Use model with thinking level shorthand- ${APP_NAME} --model sonnet:high "Solve this complex problem"-- # Limit the session to specific models- ${APP_NAME} --models claude-sonnet,claude-haiku,gpt-4o-- # Limit to a specific provider with glob pattern- ${APP_NAME} --models "github-copilot/*"-- # Scope models with fixed thinking levels- ${APP_NAME} --models sonnet:high,haiku:low-- # Start with a specific thinking level- ${APP_NAME} --thinking high "Solve this complex problem"-- # Export a session file to HTML- ${APP_NAME} session export ~/${CONFIG_DIR_NAME}/sessions/session.jsonl- ${APP_NAME} session export session.jsonl output.html-- # Work with agents- ${APP_NAME} list- ${APP_NAME} attach <agent>- ${APP_NAME} send <agent> "Use this context"--${chalk.bold("Environment Variables:")}- ANTHROPIC_API_KEY - Anthropic Claude API key- ANTHROPIC_OAUTH_TOKEN - Anthropic OAuth token (alternative to API key)- OPENAI_API_KEY - OpenAI GPT API key- PRIME_API_KEY - Prime Inference API key- AZURE_OPENAI_API_KEY - Azure OpenAI API key- AZURE_OPENAI_BASE_URL - Azure OpenAI/Cognitive Services base URL (e.g. https://{resource}.openai.azure.com)- AZURE_OPENAI_RESOURCE_NAME - Azure OpenAI resource name (alternative to base URL)- AZURE_OPENAI_API_VERSION - Azure OpenAI API version (default: v1)- AZURE_OPENAI_DEPLOYMENT_NAME_MAP - Azure OpenAI model=deployment map (comma-separated)- DEEPSEEK_API_KEY - DeepSeek API key- GEMINI_API_KEY - Google Gemini API key- GROQ_API_KEY - Groq API key- CEREBRAS_API_KEY - Cerebras API key- XAI_API_KEY - xAI Grok API key- FIREWORKS_API_KEY - Fireworks API key- OPENROUTER_API_KEY - OpenRouter API key- AI_GATEWAY_API_KEY - Vercel AI Gateway API key- ZAI_API_KEY - ZAI API key- MISTRAL_API_KEY - Mistral API key- MINIMAX_API_KEY - MiniMax API key- MOONSHOT_API_KEY - Moonshot AI API key- OPENCODE_API_KEY - OpenCode Zen/OpenCode Go API key- KIMI_API_KEY - Kimi For Coding API key- CLOUDFLARE_API_KEY - Cloudflare API token (Workers AI and AI Gateway)- CLOUDFLARE_ACCOUNT_ID - Cloudflare account id (required for both)- CLOUDFLARE_GATEWAY_ID - Cloudflare AI Gateway slug (required for AI Gateway)- XIAOMI_API_KEY - Xiaomi MiMo API key (api.xiaomimimo.com billing)- XIAOMI_TOKEN_PLAN_CN_API_KEY - Xiaomi MiMo Token Plan API key (China region)- XIAOMI_TOKEN_PLAN_AMS_API_KEY - Xiaomi MiMo Token Plan API key (Amsterdam region)- XIAOMI_TOKEN_PLAN_SGP_API_KEY - Xiaomi MiMo Token Plan API key (Singapore region)- AWS_PROFILE - AWS profile for Amazon Bedrock- AWS_ACCESS_KEY_ID - AWS access key for Amazon Bedrock- AWS_SECRET_ACCESS_KEY - AWS secret key for Amazon Bedrock- AWS_BEARER_TOKEN_BEDROCK - Bedrock API key (bearer token)- AWS_REGION - AWS region for Amazon Bedrock (e.g., us-east-1)- ${ENV_AGENT_DIR.padEnd(32)} - Config directory (default: ~/${CONFIG_DIR_NAME})- ${ENV_SESSION_DIR.padEnd(32)} - Session root directory (overridden by --session-dir)- PI_PACKAGE_DIR - Override package directory (for Nix/Guix store paths)- PI_OFFLINE - Disable startup network operations when set to 1/true/yes- PRIME_AGENT_DOWNLOAD_BASE_URL - Override the Prime Agent release manifest and tarball base URL- PI_SHARE_VIEWER_URL - Base URL for /share command (default: https://pi.dev/session/)- SERPER_API_KEY - Overrides the stored Serper key for the websearch skill (use /login to store one)- PRIME_AGENT_WEBSEARCH_TIMEOUT - websearch HTTP timeout in seconds (default: 45)- PRIME_AGENT_WEBSEARCH_NUM_RESULTS - websearch organic results to return (default: 5)--${chalk.bold("Built-in Tool Names:")}- ipython - Execute Python in a persistent IPython kernel-`);-}-function hasRequiredOptionValue(args: string[], index: number, flag: string, result: Args): boolean {const next = args[index + 1];if (next === undefined || next.startsWith("--")) {diff --git a/packages/coding-agent/src/cli/command-registry.ts b/packages/coding-agent/src/cli/command-registry.tsindex 0ca01665c5..9fcf4e813a 100644--- a/packages/coding-agent/src/cli/command-registry.ts+++ b/packages/coding-agent/src/cli/command-registry.ts@@ -158,6 +158,17 @@ export const PUBLIC_COMMAND_NAMES = new Set(export const REMOVED_COMMAND_NAMES = new Set(["app", "daemon", "install", "manage", "remove", "uninstall"]);+const TOP_LEVEL_OPTIONS = [+ ["-p, --print", "Print a response and exit"],+ ["-c, --continue", "Continue the previous session"],+ ["-r, --resume [path|id]", "Resume a session, or browse when omitted"],+ ["--model <pattern>", "Choose a model"],+ ["--thinking <level>", "Set the reasoning level"],+ ["--offline", "Disable startup network operations"],+ ["-v, --version", "Show version and exit"],+ ["-h, --help", "Show this help"],+] as const;+export function getCommandSpec(path: readonly string[]): CommandSpec | undefined {return COMMAND_SPECS.find((spec) => spec.path.length === path.length && spec.path.every((segment, index) => segment === path[index]),@@ -201,15 +212,19 @@ export function findCommandSuggestion(input: string, candidates: readonly stringexport function formatTopLevelHelp(): string {const commands = COMMAND_SPECS.filter((spec) => spec.path.length === 1);- const width = Math.max(...commands.map((spec) => spec.path[0]!.length));+ const commandWidth = Math.max(...commands.map((spec) => spec.path[0]!.length));+ const optionWidth = Math.max(...TOP_LEVEL_OPTIONS.map(([option]) => option.length));return `${APP_NAME} - AI coding assistant with an IPython toolUsage:${APP_NAME} [options] [@files...] [message...]${APP_NAME} <command> [args...]+Options:+${TOP_LEVEL_OPTIONS.map(([option, summary]) => ` ${option.padEnd(optionWidth)} ${summary}`).join("\n")}+Commands:-${commands.map((spec) => ` ${spec.path[0]!.padEnd(width)} ${spec.summary}`).join("\n")}+${commands.map((spec) => ` ${spec.path[0]!.padEnd(commandWidth)} ${spec.summary}`).join("\n")}Run "${APP_NAME} help <command>" for command details.`;}diff --git a/packages/coding-agent/src/main.ts b/packages/coding-agent/src/main.tsindex e61e9fb271..9e9e9b7a92 100644--- a/packages/coding-agent/src/main.ts+++ b/packages/coding-agent/src/main.ts@@ -11,7 +11,8 @@ import { type Api, type ImageContent, type Model, modelsAreEqual } from "@earendimport { registerBuiltinMcpOAuthProviders } from "@earendil-works/pi-ai/mcp";import { ProcessTerminal, setKeybindings, TUI } from "@earendil-works/pi-tui";import chalk from "chalk";-import { type Args, type Mode, parseArgs, printHelp } from "./cli/args.js";+import { type Args, type Mode, parseArgs } from "./cli/args.js";+import { formatTopLevelHelp } from "./cli/command-registry.js";import {ensureInteractiveDaemonRunning,isDaemonSessionSummary,@@ -181,7 +182,6 @@ export interface InteractiveDaemonStartupDecision {appMode: AppMode;startupBenchmark: boolean;noSession?: boolean;- help?: boolean;listModels?: string | true;}@@ -190,7 +190,6 @@ export function shouldUseDaemonInteractive(options: InteractiveDaemonStartupDecioptions.appMode === "interactive" &&!options.startupBenchmark &&!options.noSession &&- !options.help &&options.listModels === undefined);}@@ -1095,6 +1094,10 @@ export async function main(args: string[], options?: MainOptions) {console.log(VERSION);process.exit(0);}+ if (parsed.help) {+ console.log(formatTopLevelHelp());+ process.exit(0);+ }if (parsed.export) {let result: string;@@ -1144,7 +1147,6 @@ export async function main(args: string[], options?: MainOptions) {appMode,startupBenchmark,noSession: parsed.noSession,- help: parsed.help,listModels: parsed.listModels,});@@ -1268,8 +1270,8 @@ export async function main(args: string[], options?: MainOptions) {// Daemon mode never uses the bootstrap runtime, so skip the heavy// createAgentSessionRuntime below and start listening immediately; sessions// are created on demand through the daemon protocol via createRuntime.- // --help/--list-models still take the full path to print and exit.- if (appMode === "daemon" && !parsed.help && parsed.listModels === undefined) {+ // --list-models still takes the full path to print and exit.+ if (appMode === "daemon" && parsed.listModels === undefined) {printTimings();if (isDaemonWorkerProcess()) {await runDaemonMode({@@ -1457,15 +1459,7 @@ export async function main(args: string[], options?: MainOptions) {}const { services, session, modelFallbackMessage } = runtime;installOwnedSessionRecoveryTracking(runtime);- const { settingsManager, modelRegistry, resourceLoader } = services;-- if (parsed.help) {- const extensionFlags = resourceLoader- .getExtensions()- .extensions.flatMap((extension) => Array.from(extension.flags.values()));- printHelp(extensionFlags);- process.exit(0);- }+ const { settingsManager, modelRegistry } = services;if (parsed.listModels !== undefined) {const searchPattern = typeof parsed.listModels === "string" ? parsed.listModels : undefined;diff --git a/packages/coding-agent/test/main-interactive-routing.test.ts b/packages/coding-agent/test/main-interactive-routing.test.tsindex 590600b108..c5db711992 100644--- a/packages/coding-agent/test/main-interactive-routing.test.ts+++ b/packages/coding-agent/test/main-interactive-routing.test.ts@@ -48,13 +48,12 @@ describe("interactive startup routing", () => {});type InteractiveFallbackOverrides = Partial<- Pick<InteractiveDaemonStartupDecision, "startupBenchmark" | "noSession" | "help" | "listModels">+ Pick<InteractiveDaemonStartupDecision, "startupBenchmark" | "noSession" | "listModels">>;const fallbackCases: Array<[string, InteractiveFallbackOverrides]> = [["startup benchmark", { startupBenchmark: true }],["--no-session", { noSession: true }],- ["--help", { help: true }],["--list-models", { listModels: true }],["--list-models search", { listModels: "claude" }],];diff --git a/packages/coding-agent/test/public-command.test.ts b/packages/coding-agent/test/public-command.test.tsindex 1d184d1c90..b4c88e737e 100644--- a/packages/coding-agent/test/public-command.test.ts+++ b/packages/coding-agent/test/public-command.test.ts@@ -303,9 +303,16 @@ describe("public command routing", () => {});});- it("keeps daemon terminology out of public help", () => {+ it("formats concise top-level help", () => {const help = formatTopLevelHelp();+ expect(help).toContain("Options:");+ expect(help).toContain("-p, --print");+ expect(help).toContain("Commands:");expect(help).toContain("shutdown");expect(help).not.toContain("daemon");+ expect(help).not.toContain("Environment Variables:");+ expect(help).not.toContain("Examples:");+ expect(help).not.toContain("Built-in Tool Names:");+ expect(help).not.toContain("--autonomous");});});diff --git a/packages/coding-agent/test/stdout-cleanliness.test.ts b/packages/coding-agent/test/stdout-cleanliness.test.tsindex 4c4ae7b6a0..95b057b9ac 100644--- a/packages/coding-agent/test/stdout-cleanliness.test.ts+++ b/packages/coding-agent/test/stdout-cleanliness.test.ts@@ -81,23 +81,28 @@ async function runCli(args: string[]): Promise<{ stdout: string; stderr: string;}describe("stdout cleanliness in non-interactive modes", () => {- it("keeps stdout empty for --mode json --help while routing startup chatter to stderr", async () => {+ it("keeps stdout empty for --mode json --help without starting runtime packages", async () => {const result = await runCli(["--mode", "json", "--help"]);expect(result.code).toBe(0);expect(result.stdout).toBe("");- expect(result.stderr).toContain("changed 1 package in 471ms");- expect(result.stderr).toContain("found 0 vulnerabilities");+ expect(result.stderr).not.toContain("changed 1 package in 471ms");+ expect(result.stderr).not.toContain("found 0 vulnerabilities");expect(result.stderr).toContain("Usage:");+ expect(result.stderr).toContain("Options:");+ expect(result.stderr).toContain("Commands:");+ expect(result.stderr).not.toContain("Environment Variables:");});- it("keeps stdout empty for -p --help while routing startup chatter to stderr", async () => {- const result = await runCli(["-p", "--help"]);+ it("keeps stdout empty for -p -h without starting runtime packages", async () => {+ const result = await runCli(["-p", "-h"]);expect(result.code).toBe(0);expect(result.stdout).toBe("");- expect(result.stderr).toContain("changed 1 package in 471ms");- expect(result.stderr).toContain("found 0 vulnerabilities");+ expect(result.stderr).not.toContain("changed 1 package in 471ms");+ expect(result.stderr).not.toContain("found 0 vulnerabilities");expect(result.stderr).toContain("Usage:");+ expect(result.stderr).not.toContain("Examples:");+ expect(result.stderr).not.toContain("Built-in Tool Names:");});});