@mariozechner/pi-coding-agent 0.34.2 → 0.36.0

package/README.md

@@ -36,12 +36,11 @@ Works on Linux, macOS, and Windows (requires bash; see [Windows Setup](#windows-
   - [Custom System Prompt](#custom-system-prompt)
   - [Custom Models and Providers](#custom-models-and-providers)
   - [Settings File](#settings-file)
-- [Extensions](#extensions)
+- [Customization](#customization)
   - [Themes](#themes)
-  - [Custom Slash Commands](#custom-slash-commands)
+  - [Prompt Templates](#prompt-templates)
   - [Skills](#skills)
-  - [Hooks](#hooks)
-  - [Custom Tools](#custom-tools)
+  - [Extensions](#extensions)
 - [CLI Reference](#cli-reference)
 - [Tools](#tools)
 - [Programmatic Usage](#programmatic-usage)
@@ -156,6 +155,7 @@ Use `/login` to authenticate with subscription-based or free-tier providers:
 | GitHub Copilot | GPT-4o, Claude, Gemini via Copilot subscription | Subscription |
 | Google Gemini CLI | Gemini 2.0/2.5 models | Free (Google account) |
 | Google Antigravity | Gemini 3, Claude, GPT-OSS | Free (Google account) |
+| OpenAI Codex (ChatGPT Plus/Pro) | Codex models via ChatGPT subscription | Subscription |
 
 ```bash
 pi
@@ -173,8 +173,18 @@ pi
 - Antigravity uses a sandbox endpoint with access to Gemini 3, Claude (sonnet/opus thinking), and GPT-OSS models
 - Both are free with any Google account, subject to rate limits
 
+**OpenAI Codex notes:**
+- Requires ChatGPT Plus/Pro OAuth (`/login openai-codex`)
+- Prompt cache stored under `~/.pi/agent/cache/openai-codex/`
+- Intended for personal use with your own subscription; not for resale or multi-user services. For production, use the OpenAI Platform API.
+
 Credentials stored in `~/.pi/agent/auth.json`. Use `/logout` to clear.
 
+**Troubleshooting (OAuth):**
+- **Port 1455 in use:** Close the conflicting process or paste the auth code/URL when prompted.
+- **Token expired / refresh failed:** Run `/login` again for the provider to refresh credentials.
+- **Usage limits (429):** Wait for the reset window; pi will surface a friendly message with the approximate retry time.
+
 ### Quick Start
 
 ```bash
@@ -374,10 +384,9 @@ The output becomes part of your next prompt, formatted as:
 
 ```
 Ran `ls -la`
-```
+
 <output here>
 ```
-```
 
 Run multiple commands before prompting; all outputs are included together.
 
@@ -453,7 +462,7 @@ When disabled, neither case triggers automatic compaction (use `/compact` manual
 
 > **Note:** Compaction is lossy. The agent loses full conversation access afterward. Size tasks to avoid context limits when possible. For critical context, ask the agent to write a summary to a file, iterate on it until it covers everything, then start a new session with that file. The full session history is preserved in the JSONL file; use `/tree` to revisit any previous point.
 
-See [docs/compaction.md](docs/compaction.md) for how compaction works internally and how to customize it via hooks.
+See [docs/compaction.md](docs/compaction.md) for how compaction works internally and how to customize it via extensions.
 
 ### Branching
 
@@ -547,7 +556,7 @@ Add custom models (Ollama, vLLM, LM Studio, etc.) via `~/.pi/agent/models.json`:
 }
 ```
 
-**Supported APIs:** `openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`
+**Supported APIs:** `openai-completions`, `openai-responses`, `openai-codex-responses`, `anthropic-messages`, `google-generative-ai`
 
 **API key resolution:** The `apiKey` field is checked as environment variable name first, then used as literal value.
 
@@ -667,8 +676,7 @@ Global `~/.pi/agent/settings.json` stores persistent preferences:
   "images": {
     "autoResize": true
   },
-  "hooks": ["/path/to/hook.ts"],
-  "customTools": ["/path/to/tool.ts"]
+  "extensions": ["/path/to/extension.ts"]
 }
 ```
 
@@ -694,12 +702,11 @@ Global `~/.pi/agent/settings.json` stores persistent preferences:
 | `terminal.showImages` | Render images inline (supported terminals) | `true` |
 | `images.autoResize` | Auto-resize images to 2000x2000 max for better model compatibility | `true` |
 | `doubleEscapeAction` | Action for double-escape with empty editor: `tree` or `branch` | `tree` |
-| `hooks` | Additional hook file paths | `[]` |
-| `customTools` | Additional custom tool file paths | `[]` |
+| `extensions` | Additional extension file paths | `[]` |
 
 ---
 
-## Extensions
+## Customization
 
 ### Themes
 
@@ -720,13 +727,13 @@ Select with `/settings`, then edit the file. Changes apply on save.
 
 **VS Code terminal fix:** Set `terminal.integrated.minimumContrastRatio` to `1` for accurate colors.
 
-### Custom Slash Commands
+### Prompt Templates
 
 Define reusable prompts as Markdown files:
 
 **Locations:**
-- Global: `~/.pi/agent/commands/*.md`
-- Project: `.pi/commands/*.md`
+- Global: `~/.pi/agent/prompts/*.md`
+- Project: `.pi/prompts/*.md`
 
 **Format:**
 
@@ -755,7 +762,7 @@ Usage: `/component Button "onClick handler" "disabled support"`
 - `$1` = `Button`
 - `$@` or `$ARGUMENTS` = all arguments joined (`Button onClick handler disabled support`)
 
-**Namespacing:** Subdirectories create prefixes. `.pi/commands/frontend/component.md` → `/component (project:frontend)`
+**Namespacing:** Subdirectories create prefixes. `.pi/prompts/frontend/component.md` → `/component (project:frontend)`
 
 
 ### Skills
@@ -807,120 +814,251 @@ cd /path/to/brave-search && npm install
 
 > See [docs/skills.md](docs/skills.md) for details, examples, and links to skill repositories. pi can help you create new skills.
 
-### Hooks
+### Extensions
+
+Extensions are TypeScript modules that extend pi's behavior.
+
+**Use cases:**
+- **Custom tools** - Register tools callable by the LLM with custom UI and rendering
+- **Custom commands** - Add `/commands` for users (e.g., `/deploy`, `/stats`)
+- **Event interception** - Block tool calls, modify results, customize compaction
+- **State persistence** - Store data in session, reconstruct on reload/branch
+- **External integrations** - File watchers, webhooks, git checkpointing
+- **Custom UI** - Full TUI control from tools, commands, or event handlers
 
-Hooks are TypeScript modules that extend pi's behavior by subscribing to lifecycle events. Use them to:
+**Locations:**
+- Global: `~/.pi/agent/extensions/*.ts` or `~/.pi/agent/extensions/*/index.ts`
+- Project: `.pi/extensions/*.ts` or `.pi/extensions/*/index.ts`
+- CLI: `--extension <path>` or `-e <path>`
 
-- **Block dangerous commands** (permission gates for `rm -rf`, `sudo`, etc.)
-- **Checkpoint code state** (git stash at each turn, restore on `/branch`)
-- **Protect paths** (block writes to `.env`, `node_modules/`, etc.)
-- **Modify tool output** (filter or transform results before the LLM sees them)
-- **Inject messages from external sources to wake up the agent** (file watchers, webhooks, CI systems)
+**Dependencies:** Extensions can have their own dependencies. Place a `package.json` next to the extension (or in a parent directory), run `npm install`, and imports are resolved via [jiti](https://github.com/unjs/jiti). See [examples/extensions/with-deps/](examples/extensions/with-deps/).
 
-**Hook locations:**
-- Global: `~/.pi/agent/hooks/*.ts`
-- Project: `.pi/hooks/*.ts`
-- CLI: `--hook <path>` (for debugging)
+#### Custom Tools
 
-**Quick example** (permission gate):
+Tools are functions the LLM can call. They appear in the system prompt and can have custom rendering.
 
 ```typescript
-import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { Text } from "@mariozechner/pi-tui";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "deploy",
+    label: "Deploy",
+    description: "Deploy the application to production",
+    parameters: Type.Object({
+      environment: Type.String({ description: "Target environment" }),
+    }),
+
+    async execute(toolCallId, params, onUpdate, ctx, signal) {
+      // Show progress via onUpdate
+      onUpdate({ status: "Deploying..." });
+
+      // Ask user for confirmation
+      const ok = await ctx.ui.confirm("Deploy?", `Deploy to ${params.environment}?`);
+      if (!ok) {
+        return { content: [{ type: "text", text: "Cancelled" }], details: { cancelled: true } };
+      }
+
+      // Run shell commands
+      const result = await ctx.exec("./deploy.sh", [params.environment], { signal });
+
+      return {
+        content: [{ type: "text", text: result.stdout }],
+        details: { environment: params.environment, exitCode: result.exitCode },
+      };
+    },
+
+    // Custom TUI rendering (optional)
+    renderCall(args, theme) {
+      return new Text(theme.bold("deploy ") + theme.fg("accent", args.environment), 0, 0);
+    },
+    renderResult(result, options, theme) {
+      const ok = result.details?.exitCode === 0;
+      return new Text(ok ? theme.fg("success", "✓ Deployed") : theme.fg("error", "✗ Failed"), 0, 0);
+    },
+  });
+}
+```
 
-export default function (pi: HookAPI) {
+#### Custom Commands
+
+Commands are user-invoked via `/name`. They can show custom UI, modify state, or trigger agent turns.
+
+```typescript
+export default function (pi: ExtensionAPI) {
+  pi.registerCommand("stats", {
+    description: "Show session statistics",
+    handler: async (args, ctx) => {
+      // Simple notification
+      ctx.ui.notify(`${ctx.sessionManager.getEntries().length} entries`, "info");
+    },
+  });
+
+  pi.registerCommand("todos", {
+    description: "Interactive todo viewer",
+    handler: async (args, ctx) => {
+      // Full custom UI with keyboard handling
+      await ctx.ui.custom((tui, theme, done) => {
+        return {
+          render(width) {
+            return [
+              theme.bold("Todos"),
+              "- [ ] Item 1",
+              "- [x] Item 2",
+              "",
+              theme.fg("dim", "Press Escape to close"),
+            ];
+          },
+          handleInput(data) {
+            if (matchesKey(data, "escape")) done();
+          },
+        };
+      });
+    },
+  });
+}
+```
+
+#### Event Interception
+
+Subscribe to lifecycle events to block, modify, or observe agent behavior.
+
+```typescript
+export default function (pi: ExtensionAPI) {
+  // Block dangerous commands
   pi.on("tool_call", async (event, ctx) => {
-    if (event.toolName === "bash" && /sudo/.test(event.input.command as string)) {
-      const ok = await ctx.ui.confirm("Allow sudo?", event.input.command as string);
+    if (event.toolName === "bash" && /rm -rf/.test(event.input.command as string)) {
+      const ok = await ctx.ui.confirm("Dangerous!", "Allow rm -rf?");
       if (!ok) return { block: true, reason: "Blocked by user" };
     }
-    return undefined;
+  });
+
+  // Modify tool results
+  pi.on("tool_result", async (event, ctx) => {
+    if (event.toolName === "read") {
+      // Redact secrets from file contents
+      return { modifiedResult: event.result.replace(/API_KEY=\w+/g, "API_KEY=***") };
+    }
+  });
+
+  // Custom compaction
+  pi.on("session_before_compact", async (event, ctx) => {
+    return { customSummary: "My custom summary of the conversation so far..." };
+  });
+
+  // Git checkpoint on each turn
+  pi.on("turn_end", async (event, ctx) => {
+    await ctx.exec("git", ["stash", "push", "-m", `pi-checkpoint-${Date.now()}`]);
   });
 }
 ```
 
-**Sending messages from hooks:**
-
-Use `pi.sendMessage(message, options?)` to inject messages into the session. Messages are persisted as `CustomMessageEntry` and sent to the LLM.
+#### State Persistence
 
-Options:
-- `triggerTurn`: If true and agent is idle, starts a new agent turn. Default: false.
-- `deliverAs`: When agent is streaming, controls delivery timing:
-  - `"steer"` (default): Delivered after current tool execution, interrupts remaining tools.
-  - `"followUp"`: Delivered only after agent finishes all work.
+Store state in session entries that survive reload and work correctly with branching.
 
 ```typescript
-import * as fs from "node:fs";
-import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
-
-export default function (pi: HookAPI) {
-  pi.on("session_start", async () => {
-    fs.watch("/tmp/trigger.txt", () => {
-      const content = fs.readFileSync("/tmp/trigger.txt", "utf-8").trim();
-      if (content) {
-        pi.sendMessage({
-          customType: "file-trigger",
-          content,
-          display: true,
-        }, true);  // triggerTurn: start agent loop
+export default function (pi: ExtensionAPI) {
+  let counter = 0;
+
+  // Reconstruct state from session history
+  const reconstruct = (ctx) => {
+    counter = 0;
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type === "custom" && entry.customType === "my_counter") {
+        counter = entry.data.value;
       }
-    });
+    }
+  };
+
+  pi.on("session_start", async (e, ctx) => reconstruct(ctx));
+  pi.on("session_branch", async (e, ctx) => reconstruct(ctx));
+  pi.on("session_tree", async (e, ctx) => reconstruct(ctx));
+
+  pi.registerCommand("increment", {
+    handler: async (args, ctx) => {
+      counter++;
+      ctx.appendEntry("my_counter", { value: counter }); // Persisted in session
+      ctx.ui.notify(`Counter: ${counter}`, "info");
+    },
   });
 }
 ```
 
-> See [Hooks Documentation](docs/hooks.md) for full API reference. pi can help you create new hooks
-
-> See [examples/hooks/](examples/hooks/) for working examples including permission gates, git checkpointing, and path protection.
+#### Keyboard Shortcuts
 
-### Custom Tools
+Register custom keyboard shortcuts (shown in `/hotkeys`):
 
-Custom tools let you extend the built-in toolset (read, write, edit, bash, ...) and are called by the LLM directly. They are TypeScript modules that define tools with optional custom TUI integration for getting user input and custom tool call and result rendering.
-
-**Tool locations (auto-discovered):**
-- Global: `~/.pi/agent/tools/*/index.ts`
-- Project: `.pi/tools/*/index.ts`
+```typescript
+export default function (pi: ExtensionAPI) {
+  pi.registerShortcut("ctrl+shift+d", {
+    description: "Deploy to production",
+    handler: async (ctx) => {
+      ctx.ui.notify("Deploying...", "info");
+      await ctx.exec("./deploy.sh", []);
+    },
+  });
+}
+```
 
-**Explicit paths:**
-- CLI: `--tool <path>` (any .ts file)
-- Settings: `customTools` array in `settings.json`
+#### CLI Flags
 
-**Quick example:**
+Register custom CLI flags (parsed automatically, shown in `--help`):
 
 ```typescript
-import { Type } from "@sinclair/typebox";
-import type { CustomToolFactory } from "@mariozechner/pi-coding-agent";
-
-const factory: CustomToolFactory = (pi) => ({
-  name: "greet",
-  label: "Greeting",
-  description: "Generate a greeting",
-  parameters: Type.Object({
-    name: Type.String({ description: "Name to greet" }),
-  }),
-
-  async execute(toolCallId, params, onUpdate, ctx, signal) {
-    const { name } = params as { name: string };
-    return {
-      content: [{ type: "text", text: `Hello, ${name}!` }],
-      details: { greeted: name },
-    };
-  },
-});
+export default function (pi: ExtensionAPI) {
+  pi.registerFlag("--dry-run", {
+    description: "Run without making changes",
+    type: "boolean",
+  });
 
-export default factory;
+  pi.on("tool_call", async (event, ctx) => {
+    if (pi.getFlag("dry-run") && event.toolName === "write") {
+      return { block: true, reason: "Dry run mode" };
+    }
+  });
+}
 ```
 
-**Features:**
-- Access to `pi.cwd`, `pi.exec()`, `pi.ui` (select/confirm/input dialogs)
-- Session lifecycle via `onSession` callback (for state reconstruction)
-- Custom rendering via `renderCall()` and `renderResult()` methods
-- Streaming results via `onUpdate` callback
-- Abort handling via `signal` parameter
-- Multiple tools from one factory (return an array)
+#### Custom UI
+
+Extensions have full TUI access via `ctx.ui`:
 
-> See [Custom Tools Documentation](docs/custom-tools.md) for the full API reference, TUI component guide, and examples. pi can help you create custom tools.
+```typescript
+// Simple prompts
+const confirmed = await ctx.ui.confirm("Title", "Are you sure?");
+const choice = await ctx.ui.select("Pick one", ["Option A", "Option B"]);
+const text = await ctx.ui.input("Enter value");
+
+// Notifications
+ctx.ui.notify("Done!", "success"); // success, info, warning, error
+
+// Status line (persistent in footer, multiple extensions can set their own)
+ctx.ui.setStatus("my-ext", "Processing...");
+ctx.ui.setStatus("my-ext", null); // Clear
+
+// Widgets (above editor)
+ctx.ui.setWidget("my-ext", ["Line 1", "Line 2"]);
+
+// Full custom component with keyboard handling
+await ctx.ui.custom((tui, theme, done) => ({
+  render(width) {
+    return [
+      theme.bold("My Component"),
+      theme.fg("dim", "Press Escape to close"),
+    ];
+  },
+  handleInput(data) {
+    if (matchesKey(data, "escape")) done();
+  },
+}));
+```
 
-> See [examples/custom-tools/](examples/custom-tools/) for working examples including a todo list with session state management and a question tool with UI interaction.
+> See [docs/extensions.md](docs/extensions.md) for full API reference.
+> See [docs/tui.md](docs/tui.md) for TUI components and custom rendering.
+> See [examples/extensions/](examples/extensions/) for working examples.
 
 ---
 
@@ -934,7 +1072,7 @@ pi [options] [@files...] [messages...]
 
 | Option | Description |
 |--------|-------------|
-| `--provider <name>` | Provider: `anthropic`, `openai`, `google`, `mistral`, `xai`, `groq`, `cerebras`, `openrouter`, `zai`, `github-copilot`, `google-gemini-cli`, `google-antigravity`, or custom |
+| `--provider <name>` | Provider: `anthropic`, `openai`, `openai-codex`, `google`, `mistral`, `xai`, `groq`, `cerebras`, `openrouter`, `zai`, `github-copilot`, `google-gemini-cli`, `google-antigravity`, or custom |
 | `--model <id>` | Model ID |
 | `--api-key <key>` | API key (overrides environment) |
 | `--system-prompt <text\|file>` | Custom system prompt (text or file path) |
@@ -949,7 +1087,7 @@ pi [options] [@files...] [messages...]
 | `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling. Supports glob patterns (e.g., `anthropic/*`, `*sonnet*:high`) and fuzzy matching (e.g., `sonnet,haiku:low`) |
 | `--tools <tools>` | Comma-separated tool list (default: `read,bash,edit,write`) |
 | `--thinking <level>` | Thinking level: `off`, `minimal`, `low`, `medium`, `high` |
-| `--hook <path>` | Load a hook file (can be used multiple times) |
+| `--extension <path>`, `-e` | Load an extension file (can be used multiple times) |
 | `--no-skills` | Disable skills discovery and loading |
 | `--skills <patterns>` | Comma-separated glob patterns to filter skills (e.g., `git-*,docker`) |
 | `--export <file> [output]` | Export session to HTML |
@@ -1033,7 +1171,7 @@ Available via `--tools` flag:
 
 Example: `--tools read,grep,find,ls` for code review without modification.
 
-For adding new tools, see [Custom Tools](#custom-tools) in the Configuration section.
+For adding new tools, see [Extensions](#extensions) in the Customization section.
 
 ---
 
@@ -1068,8 +1206,8 @@ The SDK provides full control over:
 - Model selection and thinking level
 - System prompt (replace or modify)
 - Tools (built-in subsets, custom tools)
-- Hooks (inline or discovered)
-- Skills, context files, slash commands
+- Extensions (discovered or via paths)
+- Skills, context files, prompt templates
 - Session persistence (`SessionManager`)
 - Settings (`SettingsManager`)
 - API key resolution and OAuth
@@ -1101,7 +1239,7 @@ pi --export session.jsonl              # Auto-generated filename
 pi --export session.jsonl output.html  # Custom filename
 ```
 
-Works with both session files and streaming event logs from `--mode json`.
+Works with session files.
 
 ---
 
@@ -1111,13 +1249,13 @@ Pi is opinionated about what it won't do. These are intentional design decisions
 
 **No MCP.** Build CLI tools with READMEs (see [Skills](#skills)). The agent reads them on demand. [Would you like to know more?](https://mariozechner.at/posts/2025-11-02-what-if-you-dont-need-mcp/)
 
-**No sub-agents.** Spawn pi instances via tmux, or [build your own sub-agent tool](examples/custom-tools/subagent/) with [custom tools](#custom-tools). Full observability and steerability.
+**No sub-agents.** Spawn pi instances via tmux, or [build your own sub-agent tool](examples/extensions/subagent/) with [Extensions](#extensions). Full observability and steerability.
 
-**No permission popups.** Security theater. Run in a container or build your own with [Hooks](#hooks).
+**No permission popups.** Security theater. Run in a container or build your own with [Extensions](#extensions).
 
 **No plan mode.** Gather context in one session, write plans to file, start fresh for implementation.
 
-**No built-in to-dos.** They confuse models. Use a TODO.md file, or [build your own](examples/custom-tools/todo/) with [custom tools](#custom-tools).
+**No built-in to-dos.** They confuse models. Use a TODO.md file, or [build your own](examples/extensions/todo.ts) with [Extensions](#extensions).
 
 **No background bash.** Use tmux. Full observability, direct interaction.
 
@@ -1168,3 +1306,4 @@ MIT
 
 - [@mariozechner/pi-ai](https://www.npmjs.com/package/@mariozechner/pi-ai): Core LLM toolkit
 - [@mariozechner/pi-agent](https://www.npmjs.com/package/@mariozechner/pi-agent): Agent framework
+- [@mariozechner/pi-tui](https://www.npmjs.com/package/@mariozechner/pi-tui): Terminal UI components

package/dist/cli/args.d.ts

@@ -21,8 +21,7 @@ export interface Args {
     sessionDir?: string;
     models?: string[];
     tools?: ToolName[];
-    hooks?: string[];
-    customTools?: string[];
+    extensions?: string[];
     print?: boolean;
     export?: string;
     noSkills?: boolean;
@@ -30,11 +29,11 @@ export interface Args {
     listModels?: string | true;
     messages: string[];
     fileArgs: string[];
-    /** Unknown flags (potentially hook flags) - map of flag name to value */
+    /** Unknown flags (potentially extension flags) - map of flag name to value */
     unknownFlags: Map<string, boolean | string>;
 }
 export declare function isValidThinkingLevel(level: string): level is ThinkingLevel;
-export declare function parseArgs(args: string[], hookFlags?: Map<string, {
+export declare function parseArgs(args: string[], extensionFlags?: Map<string, {
     type: "boolean" | "string";
 }>): Args;
 export declare function printHelp(): void;

package/dist/cli/args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAGjE,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEjE,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AAE3C,MAAM,WAAW,IAAI;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,yEAAyE;IACzE,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC;CAC5C;AAID,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,aAAa,CAE1E;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAA;CAAE,CAAC,GAAG,IAAI,CA2GvG;AAED,wBAAgB,SAAS,IAAI,IAAI,CAiGhC","sourcesContent":["/**\n * CLI argument parsing and help display\n */\n\nimport type { ThinkingLevel } from \"@mariozechner/pi-agent-core\";\nimport chalk from \"chalk\";\nimport { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR } from \"../config.js\";\nimport { allTools, type ToolName } from \"../core/tools/index.js\";\n\nexport type Mode = \"text\" | \"json\" | \"rpc\";\n\nexport interface Args {\n\tprovider?: string;\n\tmodel?: string;\n\tapiKey?: string;\n\tsystemPrompt?: string;\n\tappendSystemPrompt?: string;\n\tthinking?: ThinkingLevel;\n\tcontinue?: boolean;\n\tresume?: boolean;\n\thelp?: boolean;\n\tversion?: boolean;\n\tmode?: Mode;\n\tnoSession?: boolean;\n\tsession?: string;\n\tsessionDir?: string;\n\tmodels?: string[];\n\ttools?: ToolName[];\n\thooks?: string[];\n\tcustomTools?: string[];\n\tprint?: boolean;\n\texport?: string;\n\tnoSkills?: boolean;\n\tskills?: string[];\n\tlistModels?: string | true;\n\tmessages: string[];\n\tfileArgs: string[];\n\t/** Unknown flags (potentially hook flags) - map of flag name to value */\n\tunknownFlags: Map<string, boolean | string>;\n}\n\nconst VALID_THINKING_LEVELS = [\"off\", \"minimal\", \"low\", \"medium\", \"high\", \"xhigh\"] as const;\n\nexport function isValidThinkingLevel(level: string): level is ThinkingLevel {\n\treturn VALID_THINKING_LEVELS.includes(level as ThinkingLevel);\n}\n\nexport function parseArgs(args: string[], hookFlags?: Map<string, { type: \"boolean\" | \"string\" }>): Args {\n\tconst result: Args = {\n\t\tmessages: [],\n\t\tfileArgs: [],\n\t\tunknownFlags: new Map(),\n\t};\n\n\tfor (let i = 0; i < args.length; i++) {\n\t\tconst arg = args[i];\n\n\t\tif (arg === \"--help\" || arg === \"-h\") {\n\t\t\tresult.help = true;\n\t\t} else if (arg === \"--version\" || arg === \"-v\") {\n\t\t\tresult.version = true;\n\t\t} else if (arg === \"--mode\" && i + 1 < args.length) {\n\t\t\tconst mode = args[++i];\n\t\t\tif (mode === \"text\" || mode === \"json\" || mode === \"rpc\") {\n\t\t\t\tresult.mode = mode;\n\t\t\t}\n\t\t} else if (arg === \"--continue\" || arg === \"-c\") {\n\t\t\tresult.continue = true;\n\t\t} else if (arg === \"--resume\" || arg === \"-r\") {\n\t\t\tresult.resume = true;\n\t\t} else if (arg === \"--provider\" && i + 1 < args.length) {\n\t\t\tresult.provider = args[++i];\n\t\t} else if (arg === \"--model\" && i + 1 < args.length) {\n\t\t\tresult.model = args[++i];\n\t\t} else if (arg === \"--api-key\" && i + 1 < args.length) {\n\t\t\tresult.apiKey = args[++i];\n\t\t} else if (arg === \"--system-prompt\" && i + 1 < args.length) {\n\t\t\tresult.systemPrompt = args[++i];\n\t\t} else if (arg === \"--append-system-prompt\" && i + 1 < args.length) {\n\t\t\tresult.appendSystemPrompt = args[++i];\n\t\t} else if (arg === \"--no-session\") {\n\t\t\tresult.noSession = true;\n\t\t} else if (arg === \"--session\" && i + 1 < args.length) {\n\t\t\tresult.session = args[++i];\n\t\t} else if (arg === \"--session-dir\" && i + 1 < args.length) {\n\t\t\tresult.sessionDir = args[++i];\n\t\t} else if (arg === \"--models\" && i + 1 < args.length) {\n\t\t\tresult.models = args[++i].split(\",\").map((s) => s.trim());\n\t\t} else if (arg === \"--tools\" && i + 1 < args.length) {\n\t\t\tconst toolNames = args[++i].split(\",\").map((s) => s.trim());\n\t\t\tconst validTools: ToolName[] = [];\n\t\t\tfor (const name of toolNames) {\n\t\t\t\tif (name in allTools) {\n\t\t\t\t\tvalidTools.push(name as ToolName);\n\t\t\t\t} else {\n\t\t\t\t\tconsole.error(\n\t\t\t\t\t\tchalk.yellow(`Warning: Unknown tool \"${name}\". Valid tools: ${Object.keys(allTools).join(\", \")}`),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t\tresult.tools = validTools;\n\t\t} else if (arg === \"--thinking\" && i + 1 < args.length) {\n\t\t\tconst level = args[++i];\n\t\t\tif (isValidThinkingLevel(level)) {\n\t\t\t\tresult.thinking = level;\n\t\t\t} else {\n\t\t\t\tconsole.error(\n\t\t\t\t\tchalk.yellow(\n\t\t\t\t\t\t`Warning: Invalid thinking level \"${level}\". Valid values: ${VALID_THINKING_LEVELS.join(\", \")}`,\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}\n\t\t} else if (arg === \"--print\" || arg === \"-p\") {\n\t\t\tresult.print = true;\n\t\t} else if (arg === \"--export\" && i + 1 < args.length) {\n\t\t\tresult.export = args[++i];\n\t\t} else if (arg === \"--hook\" && i + 1 < args.length) {\n\t\t\tresult.hooks = result.hooks ?? [];\n\t\t\tresult.hooks.push(args[++i]);\n\t\t} else if (arg === \"--tool\" && i + 1 < args.length) {\n\t\t\tresult.customTools = result.customTools ?? [];\n\t\t\tresult.customTools.push(args[++i]);\n\t\t} else if (arg === \"--no-skills\") {\n\t\t\tresult.noSkills = true;\n\t\t} else if (arg === \"--skills\" && i + 1 < args.length) {\n\t\t\t// Comma-separated glob patterns for skill filtering\n\t\t\tresult.skills = args[++i].split(\",\").map((s) => s.trim());\n\t\t} else if (arg === \"--list-models\") {\n\t\t\t// Check if next arg is a search pattern (not a flag or file arg)\n\t\t\tif (i + 1 < args.length && !args[i + 1].startsWith(\"-\") && !args[i + 1].startsWith(\"@\")) {\n\t\t\t\tresult.listModels = args[++i];\n\t\t\t} else {\n\t\t\t\tresult.listModels = true;\n\t\t\t}\n\t\t} else if (arg.startsWith(\"@\")) {\n\t\t\tresult.fileArgs.push(arg.slice(1)); // Remove @ prefix\n\t\t} else if (arg.startsWith(\"--\") && hookFlags) {\n\t\t\t// Check if it's a hook-registered flag\n\t\t\tconst flagName = arg.slice(2);\n\t\t\tconst hookFlag = hookFlags.get(flagName);\n\t\t\tif (hookFlag) {\n\t\t\t\tif (hookFlag.type === \"boolean\") {\n\t\t\t\t\tresult.unknownFlags.set(flagName, true);\n\t\t\t\t} else if (hookFlag.type === \"string\" && i + 1 < args.length) {\n\t\t\t\t\tresult.unknownFlags.set(flagName, args[++i]);\n\t\t\t\t}\n\t\t\t}\n\t\t\t// Unknown flags without hookFlags are silently ignored (first pass)\n\t\t} else if (!arg.startsWith(\"-\")) {\n\t\t\tresult.messages.push(arg);\n\t\t}\n\t}\n\n\treturn result;\n}\n\nexport function printHelp(): void {\n\tconsole.log(`${chalk.bold(APP_NAME)} - AI coding assistant with read, bash, edit, write tools\n\n${chalk.bold(\"Usage:\")}\n  ${APP_NAME} [options] [@files...] [messages...]\n\n${chalk.bold(\"Options:\")}\n  --provider <name>              Provider name (default: google)\n  --model <id>                   Model ID (default: gemini-2.5-flash)\n  --api-key <key>                API key (defaults to env vars)\n  --system-prompt <text>         System prompt (default: coding assistant prompt)\n  --append-system-prompt <text>  Append text or file contents to the system prompt\n  --mode <mode>                  Output mode: text (default), json, or rpc\n  --print, -p                    Non-interactive mode: process prompt and exit\n  --continue, -c                 Continue previous session\n  --resume, -r                   Select a session to resume\n  --session <path>               Use specific session file\n  --session-dir <dir>            Directory for session storage and lookup\n  --no-session                   Don't save session (ephemeral)\n  --models <patterns>            Comma-separated model patterns for Ctrl+P cycling\n                                 Supports globs (anthropic/*, *sonnet*) and fuzzy matching\n  --tools <tools>                Comma-separated list of tools to enable (default: read,bash,edit,write)\n                                 Available: read, bash, edit, write, grep, find, ls\n  --thinking <level>             Set thinking level: off, minimal, low, medium, high, xhigh\n  --hook <path>                  Load a hook file (can be used multiple times)\n  --tool <path>                  Load a custom tool file (can be used multiple times)\n  --no-skills                    Disable skills discovery and loading\n  --skills <patterns>            Comma-separated glob patterns to filter skills (e.g., git-*,docker)\n  --export <file>                Export session file to HTML and exit\n  --list-models [search]         List available models (with optional fuzzy search)\n  --help, -h                     Show this help\n  --version, -v                  Show version number\n\nHooks can register additional flags (e.g., --plan from plan-mode hook).\n\n${chalk.bold(\"Examples:\")}\n  # Interactive mode\n  ${APP_NAME}\n\n  # Interactive mode with initial prompt\n  ${APP_NAME} \"List all .ts files in src/\"\n\n  # Include files in initial message\n  ${APP_NAME} @prompt.md @image.png \"What color is the sky?\"\n\n  # Non-interactive mode (process and exit)\n  ${APP_NAME} -p \"List all .ts files in src/\"\n\n  # Multiple messages (interactive)\n  ${APP_NAME} \"Read package.json\" \"What dependencies do we have?\"\n\n  # Continue previous session\n  ${APP_NAME} --continue \"What did we discuss?\"\n\n  # Use different model\n  ${APP_NAME} --provider openai --model gpt-4o-mini \"Help me refactor this code\"\n\n  # Limit model cycling to specific models\n  ${APP_NAME} --models claude-sonnet,claude-haiku,gpt-4o\n\n  # Limit to a specific provider with glob pattern\n  ${APP_NAME} --models \"github-copilot/*\"\n\n  # Cycle models with fixed thinking levels\n  ${APP_NAME} --models sonnet:high,haiku:low\n\n  # Start with a specific thinking level\n  ${APP_NAME} --thinking high \"Solve this complex problem\"\n\n  # Read-only mode (no file modifications possible)\n  ${APP_NAME} --tools read,grep,find,ls -p \"Review the code in src/\"\n\n  # Export a session file to HTML\n  ${APP_NAME} --export ~/${CONFIG_DIR_NAME}/agent/sessions/--path--/session.jsonl\n  ${APP_NAME} --export session.jsonl output.html\n\n${chalk.bold(\"Environment Variables:\")}\n  ANTHROPIC_API_KEY       - Anthropic Claude API key\n  ANTHROPIC_OAUTH_TOKEN   - Anthropic OAuth token (alternative to API key)\n  OPENAI_API_KEY          - OpenAI GPT API key\n  GEMINI_API_KEY          - Google Gemini API key\n  GROQ_API_KEY            - Groq API key\n  CEREBRAS_API_KEY        - Cerebras API key\n  XAI_API_KEY             - xAI Grok API key\n  OPENROUTER_API_KEY      - OpenRouter API key\n  ZAI_API_KEY             - ZAI API key\n  ${ENV_AGENT_DIR.padEnd(23)} - Session storage directory (default: ~/${CONFIG_DIR_NAME}/agent)\n\n${chalk.bold(\"Available Tools (default: read, bash, edit, write):\")}\n  read   - Read file contents\n  bash   - Execute bash commands\n  edit   - Edit files with find/replace\n  write  - Write files (creates/overwrites)\n  grep   - Search file contents (read-only, off by default)\n  find   - Find files by glob pattern (read-only, off by default)\n  ls     - List directory contents (read-only, off by default)\n`);\n}\n"]}
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAGjE,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEjE,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AAE3C,MAAM,WAAW,IAAI;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,8EAA8E;IAC9E,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC;CAC5C;AAID,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,aAAa,CAE1E;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAA;CAAE,CAAC,GAAG,IAAI,CAwG5G;AAED,wBAAgB,SAAS,IAAI,IAAI,CAgGhC","sourcesContent":["/**\n * CLI argument parsing and help display\n */\n\nimport type { ThinkingLevel } from \"@mariozechner/pi-agent-core\";\nimport chalk from \"chalk\";\nimport { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR } from \"../config.js\";\nimport { allTools, type ToolName } from \"../core/tools/index.js\";\n\nexport type Mode = \"text\" | \"json\" | \"rpc\";\n\nexport interface Args {\n\tprovider?: string;\n\tmodel?: string;\n\tapiKey?: string;\n\tsystemPrompt?: string;\n\tappendSystemPrompt?: string;\n\tthinking?: ThinkingLevel;\n\tcontinue?: boolean;\n\tresume?: boolean;\n\thelp?: boolean;\n\tversion?: boolean;\n\tmode?: Mode;\n\tnoSession?: boolean;\n\tsession?: string;\n\tsessionDir?: string;\n\tmodels?: string[];\n\ttools?: ToolName[];\n\textensions?: string[];\n\tprint?: boolean;\n\texport?: string;\n\tnoSkills?: boolean;\n\tskills?: string[];\n\tlistModels?: string | true;\n\tmessages: string[];\n\tfileArgs: string[];\n\t/** Unknown flags (potentially extension flags) - map of flag name to value */\n\tunknownFlags: Map<string, boolean | string>;\n}\n\nconst VALID_THINKING_LEVELS = [\"off\", \"minimal\", \"low\", \"medium\", \"high\", \"xhigh\"] as const;\n\nexport function isValidThinkingLevel(level: string): level is ThinkingLevel {\n\treturn VALID_THINKING_LEVELS.includes(level as ThinkingLevel);\n}\n\nexport function parseArgs(args: string[], extensionFlags?: Map<string, { type: \"boolean\" | \"string\" }>): Args {\n\tconst result: Args = {\n\t\tmessages: [],\n\t\tfileArgs: [],\n\t\tunknownFlags: new Map(),\n\t};\n\n\tfor (let i = 0; i < args.length; i++) {\n\t\tconst arg = args[i];\n\n\t\tif (arg === \"--help\" || arg === \"-h\") {\n\t\t\tresult.help = true;\n\t\t} else if (arg === \"--version\" || arg === \"-v\") {\n\t\t\tresult.version = true;\n\t\t} else if (arg === \"--mode\" && i + 1 < args.length) {\n\t\t\tconst mode = args[++i];\n\t\t\tif (mode === \"text\" || mode === \"json\" || mode === \"rpc\") {\n\t\t\t\tresult.mode = mode;\n\t\t\t}\n\t\t} else if (arg === \"--continue\" || arg === \"-c\") {\n\t\t\tresult.continue = true;\n\t\t} else if (arg === \"--resume\" || arg === \"-r\") {\n\t\t\tresult.resume = true;\n\t\t} else if (arg === \"--provider\" && i + 1 < args.length) {\n\t\t\tresult.provider = args[++i];\n\t\t} else if (arg === \"--model\" && i + 1 < args.length) {\n\t\t\tresult.model = args[++i];\n\t\t} else if (arg === \"--api-key\" && i + 1 < args.length) {\n\t\t\tresult.apiKey = args[++i];\n\t\t} else if (arg === \"--system-prompt\" && i + 1 < args.length) {\n\t\t\tresult.systemPrompt = args[++i];\n\t\t} else if (arg === \"--append-system-prompt\" && i + 1 < args.length) {\n\t\t\tresult.appendSystemPrompt = args[++i];\n\t\t} else if (arg === \"--no-session\") {\n\t\t\tresult.noSession = true;\n\t\t} else if (arg === \"--session\" && i + 1 < args.length) {\n\t\t\tresult.session = args[++i];\n\t\t} else if (arg === \"--session-dir\" && i + 1 < args.length) {\n\t\t\tresult.sessionDir = args[++i];\n\t\t} else if (arg === \"--models\" && i + 1 < args.length) {\n\t\t\tresult.models = args[++i].split(\",\").map((s) => s.trim());\n\t\t} else if (arg === \"--tools\" && i + 1 < args.length) {\n\t\t\tconst toolNames = args[++i].split(\",\").map((s) => s.trim());\n\t\t\tconst validTools: ToolName[] = [];\n\t\t\tfor (const name of toolNames) {\n\t\t\t\tif (name in allTools) {\n\t\t\t\t\tvalidTools.push(name as ToolName);\n\t\t\t\t} else {\n\t\t\t\t\tconsole.error(\n\t\t\t\t\t\tchalk.yellow(`Warning: Unknown tool \"${name}\". Valid tools: ${Object.keys(allTools).join(\", \")}`),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t\tresult.tools = validTools;\n\t\t} else if (arg === \"--thinking\" && i + 1 < args.length) {\n\t\t\tconst level = args[++i];\n\t\t\tif (isValidThinkingLevel(level)) {\n\t\t\t\tresult.thinking = level;\n\t\t\t} else {\n\t\t\t\tconsole.error(\n\t\t\t\t\tchalk.yellow(\n\t\t\t\t\t\t`Warning: Invalid thinking level \"${level}\". Valid values: ${VALID_THINKING_LEVELS.join(\", \")}`,\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}\n\t\t} else if (arg === \"--print\" || arg === \"-p\") {\n\t\t\tresult.print = true;\n\t\t} else if (arg === \"--export\" && i + 1 < args.length) {\n\t\t\tresult.export = args[++i];\n\t\t} else if ((arg === \"--extension\" || arg === \"-e\") && i + 1 < args.length) {\n\t\t\tresult.extensions = result.extensions ?? [];\n\t\t\tresult.extensions.push(args[++i]);\n\t\t} else if (arg === \"--no-skills\") {\n\t\t\tresult.noSkills = true;\n\t\t} else if (arg === \"--skills\" && i + 1 < args.length) {\n\t\t\t// Comma-separated glob patterns for skill filtering\n\t\t\tresult.skills = args[++i].split(\",\").map((s) => s.trim());\n\t\t} else if (arg === \"--list-models\") {\n\t\t\t// Check if next arg is a search pattern (not a flag or file arg)\n\t\t\tif (i + 1 < args.length && !args[i + 1].startsWith(\"-\") && !args[i + 1].startsWith(\"@\")) {\n\t\t\t\tresult.listModels = args[++i];\n\t\t\t} else {\n\t\t\t\tresult.listModels = true;\n\t\t\t}\n\t\t} else if (arg.startsWith(\"@\")) {\n\t\t\tresult.fileArgs.push(arg.slice(1)); // Remove @ prefix\n\t\t} else if (arg.startsWith(\"--\") && extensionFlags) {\n\t\t\t// Check if it's an extension-registered flag\n\t\t\tconst flagName = arg.slice(2);\n\t\t\tconst extFlag = extensionFlags.get(flagName);\n\t\t\tif (extFlag) {\n\t\t\t\tif (extFlag.type === \"boolean\") {\n\t\t\t\t\tresult.unknownFlags.set(flagName, true);\n\t\t\t\t} else if (extFlag.type === \"string\" && i + 1 < args.length) {\n\t\t\t\t\tresult.unknownFlags.set(flagName, args[++i]);\n\t\t\t\t}\n\t\t\t}\n\t\t\t// Unknown flags without extensionFlags are silently ignored (first pass)\n\t\t} else if (!arg.startsWith(\"-\")) {\n\t\t\tresult.messages.push(arg);\n\t\t}\n\t}\n\n\treturn result;\n}\n\nexport function printHelp(): void {\n\tconsole.log(`${chalk.bold(APP_NAME)} - AI coding assistant with read, bash, edit, write tools\n\n${chalk.bold(\"Usage:\")}\n  ${APP_NAME} [options] [@files...] [messages...]\n\n${chalk.bold(\"Options:\")}\n  --provider <name>              Provider name (default: google)\n  --model <id>                   Model ID (default: gemini-2.5-flash)\n  --api-key <key>                API key (defaults to env vars)\n  --system-prompt <text>         System prompt (default: coding assistant prompt)\n  --append-system-prompt <text>  Append text or file contents to the system prompt\n  --mode <mode>                  Output mode: text (default), json, or rpc\n  --print, -p                    Non-interactive mode: process prompt and exit\n  --continue, -c                 Continue previous session\n  --resume, -r                   Select a session to resume\n  --session <path>               Use specific session file\n  --session-dir <dir>            Directory for session storage and lookup\n  --no-session                   Don't save session (ephemeral)\n  --models <patterns>            Comma-separated model patterns for Ctrl+P cycling\n                                 Supports globs (anthropic/*, *sonnet*) and fuzzy matching\n  --tools <tools>                Comma-separated list of tools to enable (default: read,bash,edit,write)\n                                 Available: read, bash, edit, write, grep, find, ls\n  --thinking <level>             Set thinking level: off, minimal, low, medium, high, xhigh\n  --extension, -e <path>         Load an extension file (can be used multiple times)\n  --no-skills                    Disable skills discovery and loading\n  --skills <patterns>            Comma-separated glob patterns to filter skills (e.g., git-*,docker)\n  --export <file>                Export session file to HTML and exit\n  --list-models [search]         List available models (with optional fuzzy search)\n  --help, -h                     Show this help\n  --version, -v                  Show version number\n\nExtensions can register additional flags (e.g., --plan from plan-mode extension).\n\n${chalk.bold(\"Examples:\")}\n  # Interactive mode\n  ${APP_NAME}\n\n  # Interactive mode with initial prompt\n  ${APP_NAME} \"List all .ts files in src/\"\n\n  # Include files in initial message\n  ${APP_NAME} @prompt.md @image.png \"What color is the sky?\"\n\n  # Non-interactive mode (process and exit)\n  ${APP_NAME} -p \"List all .ts files in src/\"\n\n  # Multiple messages (interactive)\n  ${APP_NAME} \"Read package.json\" \"What dependencies do we have?\"\n\n  # Continue previous session\n  ${APP_NAME} --continue \"What did we discuss?\"\n\n  # Use different model\n  ${APP_NAME} --provider openai --model gpt-4o-mini \"Help me refactor this code\"\n\n  # Limit model cycling to specific models\n  ${APP_NAME} --models claude-sonnet,claude-haiku,gpt-4o\n\n  # Limit to a specific provider with glob pattern\n  ${APP_NAME} --models \"github-copilot/*\"\n\n  # Cycle models with fixed thinking levels\n  ${APP_NAME} --models sonnet:high,haiku:low\n\n  # Start with a specific thinking level\n  ${APP_NAME} --thinking high \"Solve this complex problem\"\n\n  # Read-only mode (no file modifications possible)\n  ${APP_NAME} --tools read,grep,find,ls -p \"Review the code in src/\"\n\n  # Export a session file to HTML\n  ${APP_NAME} --export ~/${CONFIG_DIR_NAME}/agent/sessions/--path--/session.jsonl\n  ${APP_NAME} --export session.jsonl output.html\n\n${chalk.bold(\"Environment Variables:\")}\n  ANTHROPIC_API_KEY       - Anthropic Claude API key\n  ANTHROPIC_OAUTH_TOKEN   - Anthropic OAuth token (alternative to API key)\n  OPENAI_API_KEY          - OpenAI GPT API key\n  GEMINI_API_KEY          - Google Gemini API key\n  GROQ_API_KEY            - Groq API key\n  CEREBRAS_API_KEY        - Cerebras API key\n  XAI_API_KEY             - xAI Grok API key\n  OPENROUTER_API_KEY      - OpenRouter API key\n  ZAI_API_KEY             - ZAI API key\n  ${ENV_AGENT_DIR.padEnd(23)} - Session storage directory (default: ~/${CONFIG_DIR_NAME}/agent)\n\n${chalk.bold(\"Available Tools (default: read, bash, edit, write):\")}\n  read   - Read file contents\n  bash   - Execute bash commands\n  edit   - Edit files with find/replace\n  write  - Write files (creates/overwrites)\n  grep   - Search file contents (read-only, off by default)\n  find   - Find files by glob pattern (read-only, off by default)\n  ls     - List directory contents (read-only, off by default)\n`);\n}\n"]}