File reference (@): Type @ to fuzzy-search project files. Respects .gitignore.

Path completion (Tab): Complete relative paths, ../, ~/, etc.

Drag & drop: Drag files from your file manager into the terminal.

Multi-line paste: Pasted content is collapsed to [paste #N lines] but sent in full.

Message queuing: Submit messages while the agent is working:
- Enter queues a steering message, delivered after current tool execution (interrupts remaining tools)
- Alt+Enter queues a follow-up message, delivered only after the agent finishes all work

Both modes are configurable via /settings: "one-at-a-time" delivers messages one by one waiting for responses, "all" delivers all queued messages at once. Press Escape to abort and restore queued messages to editor.

$3

Navigation:

| Key | Action |
|-----|--------|
| Arrow keys | Move cursor / browse history (Up when empty) |
| Option+Left/Right | Move by word |
| Ctrl+A / Home / Cmd+Left | Start of line |
| Ctrl+E / End / Cmd+Right | End of line |

Editing:

| Key | Action |
|-----|--------|
| Enter | Send message |
| Shift+Enter | New line (Ctrl+Enter on Windows Terminal) |
| Ctrl+W / Option+Backspace | Delete word backwards |
| Ctrl+U | Delete to start of line |
| Ctrl+K | Delete to end of line |

Other:

| Key | Action |
|-----|--------|
| Tab | Path completion / accept autocomplete |
| Escape | Cancel autocomplete / abort streaming |
| Ctrl+C | Clear editor (first) / exit (second) |
| Ctrl+D | Exit (when editor is empty) |
| Ctrl+Z | Suspend to background (use fg in shell to resume) |
| Shift+Tab | Cycle thinking level |
| Ctrl+P / Shift+Ctrl+P | Cycle models forward/backward (scoped by --models) |
| Ctrl+L | Open model selector |
| Ctrl+O | Toggle tool output expansion |
| Ctrl+T | Toggle thinking block visibility |
| Ctrl+G | Edit message in external editor ($VISUAL or $EDITOR) |
| Ctrl+V | Paste image from clipboard |
| Alt+Up | Restore queued messages to editor |

$3

All keyboard shortcuts can be customized via ~/.pi/agent/keybindings.json. Each action can be bound to one or more keys.

Key format: modifier+key where modifiers are ctrl, shift, alt and keys are:

- Letters: a-z
- Numbers: 0-9
- Special keys: escape, tab, enter, space, backspace, delete, home, end, up, down, left, right
- Symbol keys: `, -, =, [, ], \, ;, ', ,, ., /, !, @, #, $, %, ^, &, *, (, ), _, +, |, ~, {, }, :, <, >, ?

Configurable actions:

| Action | Default | Description |
|--------|---------|-------------|
| cursorUp | up | Move cursor up |
| cursorDown | down | Move cursor down |
| cursorLeft | left | Move cursor left |
| cursorRight | right | Move cursor right |
| cursorWordLeft | alt+left, ctrl+left | Move cursor word left |
| cursorWordRight | alt+right, ctrl+right | Move cursor word right |
| cursorLineStart | home, ctrl+a | Move to line start |
| cursorLineEnd | end, ctrl+e | Move to line end |
| deleteCharBackward | backspace | Delete char backward |
| deleteCharForward | delete | Delete char forward |
| deleteWordBackward | ctrl+w, alt+backspace | Delete word backward |
| deleteToLineStart | ctrl+u | Delete to line start |
| deleteToLineEnd | ctrl+k | Delete to line end |
| newLine | shift+enter | Insert new line |
| submit | enter | Submit input |
| tab | tab | Tab/autocomplete |
| interrupt | escape | Interrupt operation |
| clear | ctrl+c | Clear editor |
| exit | ctrl+d | Exit (when empty) |
| suspend | ctrl+z | Suspend process |
| cycleThinkingLevel | shift+tab | Cycle thinking level |
| cycleModelForward | ctrl+p | Next model |
| cycleModelBackward | shift+ctrl+p | Previous model |
| selectModel | ctrl+l | Open model selector |
| expandTools | ctrl+o | Expand tool output |
| toggleThinking | ctrl+t | Toggle thinking |
| externalEditor | ctrl+g | Open external editor |
| followUp | alt+enter | Queue follow-up message |
| dequeue | alt+up | Restore queued messages to editor |
| selectUp | up | Move selection up in lists (session picker, model selector) |
| selectDown | down | Move selection down in lists |
| selectConfirm | enter | Confirm selection |
| selectCancel | escape, ctrl+c | Cancel selection |

Example (Emacs-style):

`json
{
"cursorUp": ["up", "ctrl+p"],
"cursorDown": ["down", "ctrl+n"],
"cursorLeft": ["left", "ctrl+b"],
"cursorRight": ["right", "ctrl+f"],
"cursorWordLeft": ["alt+left", "alt+b"],
"cursorWordRight": ["alt+right", "alt+f"],
"deleteCharForward": ["delete", "ctrl+d"],
"deleteCharBackward": ["backspace", "ctrl+h"],
"newLine": ["shift+enter", "ctrl+j"]
}
`

Example (Vim-style):

`json
{
"cursorUp": ["up", "alt+k"],
"cursorDown": ["down", "alt+j"],
"cursorLeft": ["left", "alt+h"],
"cursorRight": ["right", "alt+l"],
"cursorWordLeft": ["alt+left", "alt+b"],
"cursorWordRight": ["alt+right", "alt+w"],
"deleteCharBackward": ["backspace", "ctrl+h"],
"deleteWordBackward": ["ctrl+w", "alt+backspace"]
}
`

Example (symbol keys):

`json
{
"submit": ["enter", "ctrl+j"],
"newLine": ["shift+enter", "ctrl+;"],
"toggleThinking": "ctrl+/",
"cycleModelForward": "ctrl+.",
"cycleModelBackward": "ctrl+,",
"interrupt": ["escape", "ctrl+"]
}
``

> Note: Some ctrl+symbol combinations overlap with ASCII control characters due to terminal legacy behavior (e.g., ctrl+[ is the same as Escape, ctrl+M is the same as Enter). These can still be used with ctrl+shift+key (e.g., ctrl+shift+]). See Kitty keyboard protocol: legacy ctrl mapping of ASCII keys for all unsupported keys.

$3

Prefix commands with ! to execute them and add output to context:

`
!ls -la
!git status
!cat package.json | jq '.dependencies'
`

Output streams in real-time. Press Escape to cancel. Large outputs truncate at 2000 lines / 50KB.

The output becomes part of your next prompt, formatted as:

`
Ran ls -la

`

Run multiple commands before prompting; all outputs are included together.

$3

Pasting images: Press Ctrl+V to paste an image from your clipboard.

> Note: On macOS, pressing Cmd+C on an image file in Finder copies the file path, not the image contents. Use Preview or another image viewer to copy the actual image, or drag the file onto the terminal instead.

Dragging images: Drag image files onto the terminal to insert their path. On macOS, you can also drag the screenshot thumbnail (after Cmd+Shift+4) directly onto the terminal.

Attaching images: Include image paths in your message:

`
You: What's in this screenshot? /path/to/image.png
`

Supported formats: .jpg, .jpeg, .png, .gif, .webp

Auto-resize: Images larger than 2000x2000 pixels are automatically resized to fit within this limit for better compatibility with Anthropic models. The original dimensions are noted in the context so the model can map coordinates back if needed. Disable via images.autoResize: false in settings.

Inline rendering: On terminals that support the Kitty graphics protocol (Kitty, Ghostty, WezTerm) or iTerm2 inline images, images in tool output are rendered inline. On unsupported terminals, a text placeholder is shown instead.

Toggle inline images via /settings or set terminal.showImages: false in settings.

---

Sessions

Sessions are stored as JSONL files with a tree structure. Each entry has an id and parentId, enabling in-place branching: navigate to any previous point with /tree, continue from there, and switch between branches while preserving all history in a single file.

See docs/session.md for the file format and programmatic API.

$3

Sessions auto-save to ~/.pi/agent/sessions/ organized by working directory.

`bash
pi --continue # Continue most recent session
pi -c # Short form

pi --resume # Browse and select from past sessions (Tab to toggle Current Folder / All)
pi -r # Short form

pi --no-session # Ephemeral mode (don't save)

pi --session /path/to/file.jsonl # Use specific session file
pi --session a8ec1c2a # Resume by session ID (partial UUID)
`

Resuming by session ID: The --session flag accepts a session UUID (or prefix). Session IDs are visible in filenames under ~/.pi/agent/sessions// (e.g., 2025-12-13T17-47-46-817Z_a8ec1c2a-5a5f-4699-88cb-03e7d3cb9292.jsonl). The UUID is the part after the underscore. You can also search by session ID in the pi -r picker.

$3

Long sessions can exhaust context windows. Compaction summarizes older messages while keeping recent ones.

Manual: /compact or /compact Focus on the API changes

Automatic: Enable via /settings. When enabled, triggers in two cases:
- Overflow recovery: LLM returns context overflow error. Compacts and auto-retries.
- Threshold maintenance: Context exceeds contextWindow - reserveTokens after a successful turn. Compacts without retry.

When disabled, neither case triggers automatic compaction (use /compact manually if needed).

Configuration (~/.pi/agent/settings.json):

`json
{
"compaction": {
"enabled": true,
"reserveTokens": 16384,
"keepRecentTokens": 20000
}
}
`

> 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 for how compaction works internally and how to customize it via extensions.

$3

In-place navigation (/tree): Navigate the session tree without creating new files. Select any previous point, continue from there, and switch between branches while preserving all history.

- Search by typing, page with ←/→
- Filter modes (Ctrl+O): default → no-tools → user-only → labeled-only → all
- Press l to label entries as bookmarks
- When switching branches, you're prompted whether to generate a summary of the abandoned branch (messages up to the common ancestor)

Create new session (/fork): Fork to a new session file:

1. Opens selector showing all your user messages
2. Select a message to fork from
3. Creates new session with history up to that point
4. Selected message placed in editor for modification

---

Configuration

$3

Pi loads AGENTS.md (or CLAUDE.md) files at startup in this order:

1. Global: ~/.pi/agent/AGENTS.md
2. Parent directories: Walking up from current directory
3. Current directory: ./AGENTS.md

Use these for:
- Project instructions and guidelines
- Common commands and workflows
- Architecture documentation
- Coding conventions
- Testing instructions

`markdown


Common Commands

Replace the default system prompt entirely by creating a SYSTEM.md file:

1. Project-local: .pi/SYSTEM.md (takes precedence)
2. Global: ~/.pi/agent/SYSTEM.md (fallback)

This is useful when using pi as different types of agents across repos (coding assistant, personal assistant, domain-specific agent, etc.).

`markdown
You are a technical writing assistant. Help users write clear documentation.

Focus on:
- Concise explanations
- Code examples
- Proper formatting
`

The --system-prompt CLI flag overrides both files.

$3

To add instructions to the system prompt without replacing the default (preserving automatic loading of AGENTS.md context files, skills, and tools guidelines), create an APPEND_SYSTEM.md file:

1. Project-local: .pi/APPEND_SYSTEM.md (takes precedence)
2. Global: ~/.pi/agent/APPEND_SYSTEM.md (fallback)

The --append-system-prompt CLI flag overrides both files.

$3

Add custom models (Ollama, vLLM, LM Studio, etc.) via ~/.pi/agent/models.json:

`json
{
"providers": {
"ollama": {
"baseUrl": "http://localhost:11434/v1",
"apiKey": "OLLAMA_API_KEY",
"api": "openai-completions",
"models": [
{
"id": "llama-3.1-8b",
"name": "Llama 3.1 8B (Local)",
"reasoning": false,
"input": ["text"],
"cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
"contextWindow": 128000,
"maxTokens": 32000
}
]
}
}
}
`

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.

API override: Set api at provider level (default for all models) or model level (override per model).

Custom headers:

`json
{
"providers": {
"custom-proxy": {
"baseUrl": "https://proxy.example.com/v1",
"apiKey": "YOUR_API_KEY",
"api": "anthropic-messages",
"headers": {
"User-Agent": "Mozilla/5.0 ...",
"X-Custom-Auth": "token"
},
"models": [...]
}
}
}
`

Overriding built-in providers:

To route a built-in provider (anthropic, openai, google, etc.) through a proxy without redefining all models, just specify the baseUrl:

`json
{
"providers": {
"anthropic": {
"baseUrl": "https://my-proxy.example.com/v1"
}
}
}
`

All built-in Anthropic models remain available with the new endpoint. Existing OAuth or API key auth continues to work.

To fully replace a built-in provider with custom models, include the models array:

`json
{
"providers": {
"anthropic": {
"baseUrl": "https://my-proxy.example.com/v1",
"apiKey": "ANTHROPIC_API_KEY",
"api": "anthropic-messages",
"models": [...]
}
}
}
`

Authorization header: Set authHeader: true to add Authorization: Bearer automatically.

OpenAI compatibility (compat field):

| Field | Description |
|-------|-------------|
| supportsStore | Whether provider supports store field |
| supportsDeveloperRole | Use developer vs system role |
| supportsReasoningEffort | Support for reasoning_effort parameter |
| supportsUsageInStreaming | Whether provider supports stream_options: { include_usage: true }. Default: true |
| maxTokensField | Use max_completion_tokens or max_tokens |

Live reload: The file reloads each time you open /model. Edit during session; no restart needed.

Model selection priority:
1. CLI args (--provider, --model)
2. First from --models scope (new sessions only)
3. Restored from session (--continue, --resume)
4. Saved default from settings
5. First available model with valid API key

> pi can help you create custom provider and model configurations.

$3

Settings are loaded from two locations and merged:

1. Global: ~/.pi/agent/settings.json - user preferences
2. Project: /.pi/settings.json - project-specific overrides (version control friendly)

Project settings override global settings. For nested objects, individual keys merge. Settings changed via TUI (model, thinking level, etc.) are saved to global preferences only.

Global ~/.pi/agent/settings.json stores persistent preferences:

`json
{
"theme": "dark",
"defaultProvider": "anthropic",
"defaultModel": "claude-sonnet-4-20250514",
"defaultThinkingLevel": "medium",
"enabledModels": ["anthropic/", "gpt*", "gemini-2.5-pro:high"],
"steeringMode": "one-at-a-time",
"followUpMode": "one-at-a-time",
"shellPath": "C:\\path\\to\\bash.exe",
"hideThinkingBlock": false,
"collapseChangelog": false,
"compaction": {
"enabled": true,
"reserveTokens": 16384,
"keepRecentTokens": 20000
},
"skills": {
"enabled": true
},
"retry": {
"enabled": true,
"maxRetries": 3,
"baseDelayMs": 2000
},
"terminal": {
"showImages": true
},
"images": {
"autoResize": true,
"blockImages": false
},
"extensions": ["/path/to/extension.ts"]
}
`

| Setting | Description | Default |
|---------|-------------|---------|
| theme | Color theme name | auto-detected |
| defaultProvider | Default model provider | - |
| defaultModel | Default model ID | - |
| defaultThinkingLevel | Thinking level: off, minimal, low, medium, high, xhigh | - |
| enabledModels | Model patterns for cycling. Supports glob patterns (github-copilot/, sonnet*) and fuzzy matching. Same as --models CLI flag | - |
| steeringMode | Steering message delivery: all or one-at-a-time | one-at-a-time |
| followUpMode | Follow-up message delivery: all or one-at-a-time | one-at-a-time |
| shellPath | Custom bash path (Windows) | auto-detected |
| hideThinkingBlock | Hide thinking blocks in output (Ctrl+T to toggle) | false |
| collapseChangelog | Show condensed changelog after update | false |
| compaction.enabled | Enable auto-compaction | true |
| compaction.reserveTokens | Tokens to reserve before compaction triggers | 16384 |
| compaction.keepRecentTokens | Recent tokens to keep after compaction | 20000 |
| skills.enabled | Enable skills discovery | true |
| retry.enabled | Auto-retry on transient errors | true |
| retry.maxRetries | Maximum retry attempts | 3 |
| retry.baseDelayMs | Base delay for exponential backoff | 2000 |
| terminal.showImages | Render images inline (supported terminals) | true |
| images.autoResize | Auto-resize images to 2000x2000 max for better model compatibility | true |
| images.blockImages | Prevent images from being sent to LLM providers | false |
| doubleEscapeAction | Action for double-escape with empty editor: tree or branch | tree |
| extensions | Additional extension file paths | [] |

---

Customization

$3

Built-in themes: dark (default), light. Auto-detected on first run.

Select theme via /settings or set in ~/.pi/agent/settings.json.

Custom themes: Create ~/.pi/agent/themes/*.json. Custom themes support live reload.

`bash
mkdir -p ~/.pi/agent/themes
cp $(npm root -g)/@cargo-cult/pi-coding-agent/dist/theme/dark.json ~/.pi/agent/themes/my-theme.json
`

Select with /settings, then edit the file. Changes apply on save.

> See Theme Documentation on how to create custom themes in detail. Pi can help you create a new one.

VS Code terminal fix: Set terminal.integrated.minimumContrastRatio to 1 for accurate colors.

$3

Define reusable prompts as Markdown files:

Locations:
- Global: ~/.pi/agent/prompts/*.md
- Project: .pi/prompts/*.md

Format:

`markdown
---
description: Review staged git changes
---
Review the staged changes (git diff --cached). Focus on:
- Bugs and logic errors
- Security issues
- Error handling gaps
`

Filename (without .md) becomes the command name. Description shown in autocomplete.

Arguments:

`markdown
---
description: Create a component
---
Create a React component named $1 with features: $@
`

Usage: /component Button "onClick handler" "disabled support"
- $1 = Button
- $@ or $ARGUMENTS = all arguments joined (Button onClick handler disabled support)

Namespacing: Subdirectories create prefixes. .pi/prompts/frontend/component.md → /component (project:frontend)

$3

Skills are self-contained capability packages that the agent loads on-demand. Pi implements the Agent Skills standard, warning about violations but remaining lenient.

A skill provides specialized workflows, setup instructions, helper scripts, and reference documentation for specific tasks. Skills are loaded when the agent decides a task matches the description, or when you explicitly ask to use one. You can also invoke skills directly via /skill:name commands (e.g., /skill:brave-search).

Example use cases:
- Web search and content extraction (Brave Search API)
- Browser automation via Chrome DevTools Protocol
- Google Calendar, Gmail, Drive integration
- PDF/DOCX processing and creation
- Speech-to-text transcription
- YouTube transcript extraction

Skill locations:
- Pi user: ~/.pi/agent/skills/**/SKILL.md (recursive)
- Pi project: .pi/skills/**/SKILL.md (recursive)
- Claude Code: ~/.claude/skills//SKILL.md and .claude/skills//SKILL.md
- Codex CLI: ~/.codex/skills/**/SKILL.md (recursive)

Format:

`markdown
---
name: brave-search
description: Web search via Brave Search API. Use for documentation, facts, or web content.
---

Brave Search

Setup

- name: Required. Must match parent directory name. Lowercase, hyphens, max 64 chars.
- description: Required. Max 1024 chars. Determines when the skill is loaded.

Disable skills: pi --no-skills or set skills.enabled: false in settings.

> See docs/skills.md for details, examples, and links to skill repositories. pi can help you create new skills.

$3

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/fork
- External integrations - File watchers, webhooks, git checkpointing
- Custom UI - Full TUI control from tools, commands, or event handlers

Locations:
- Global: ~/.pi/agent/extensions/.ts or ~/.pi/agent/extensions//index.ts
- Project: .pi/extensions/.ts or .pi/extensions//index.ts
- CLI: --extension or -e

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. See examples/extensions/with-deps/.

#### Custom Tools

Tools are functions the LLM can call. They appear in the system prompt and can have custom rendering.

`typescript
import type { ExtensionAPI } from "@cargo-cult/pi-coding-agent";
import { Type } from "@sinclair/typebox";
import { Text } from "@cargo-cult/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);
},
});
}
`

#### 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" && /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" };
}
});

// 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()}]);
});
}
`

#### State Persistence

Store state in session entries that survive reload and work correctly with branching.

`typescript
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_fork", 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");
},
});
}
`

#### Keyboard Shortcuts

Register custom keyboard shortcuts (shown in /hotkeys):

`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", []);
},
});
}
`

#### CLI Flags

Register custom CLI flags (parsed automatically, shown in --help):

`typescript
export default function (pi: ExtensionAPI) {
pi.registerFlag("dry-run", {
description: "Run without making changes",
type: "boolean",
});

pi.on("tool_call", async (event, ctx) => {
if (pi.getFlag("dry-run") && event.toolName === "write") {
return { block: true, reason: "Dry run mode" };
}
});
}
`

#### Custom UI

Extensions have full TUI access via ctx.ui:

`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"]);

// Custom footer (replaces built-in footer)
ctx.ui.setFooter((tui, theme) => ({
render(width) { return [theme.fg("dim", "Custom footer")]; },
invalidate() {},
}));
ctx.ui.setFooter(undefined); // Restore built-in footer

// 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 docs/extensions.md for full API reference.
> See docs/tui.md for TUI components and custom rendering.
> See examples/extensions/ for working examples.

---

CLI Reference

`bash
pi [options] [@files...] [messages...]
`

$3

| Option | Description |
|--------|-------------|
| --provider | Provider: anthropic, openai, openai-codex, google, google-vertex, amazon-bedrock, mistral, xai, groq, cerebras, openrouter, vercel-ai-gateway, zai, minimax, minimax-cn, github-copilot, google-gemini-cli, google-antigravity, or custom |
| --model | Model ID |
| --api-key | API key (overrides environment) |
| --system-prompt | Custom system prompt (text or file path) |
| --append-system-prompt | Append to system prompt |
| --mode | Output mode: text, json, rpc (implies --print) |
| --print, -p | Non-interactive: process prompt and exit |
| --no-session | Don't save session |
| --session | Use specific session file |
| --session-dir