Skip to content

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.md
index 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.md
index 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 set
pi --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 Arguments
diff --git a/packages/coding-agent/src/cli/args.ts b/packages/coding-agent/src/cli/args.ts
index 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.ts
index 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 string
export 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 tool
Usage:
${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.ts
index 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 "@earend
import { 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: InteractiveDaemonStartupDeci
options.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.ts
index 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.ts
index 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.ts
index 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:");
});
});