rpi — reference manual

rpi is a terminal coding agent for Pi v3 sessions: a single Rust binary that switches between print mode, a line REPL, a full-screen inline TUI, and headless JSON/RPC modes. It supports multiple model providers, local llama.cpp models, extensions, skills, prompt templates, packages, session export and sharing, a security model built around project trust and credential redaction, and a full orchestration stack: durable goals, Todo DAGs, subagent jobs with IRC coordination, isolated concurrent workflows, MCP/ACP protocol clients, voice input, memory backends, and host hooks.

Getting started

• Quick start — first-run workflow
• Installation — supported platforms, installers, verification

User guide

• TUI and keybindings
• CLI modes and commands
• Goals
• Todos and the Todo DAG
• Orchestration: subagents, jobs, and IRC
• Isolated concurrent workflows
• Session recovery: rewind, checkpoints, handoffs, and TTL
• Live voice (/live)
• Models and custom providers
• Authentication
• RPC JSONL protocol
• Web client (/web)
• E2E scenarios (user-perspective tmux tests)

Reference

• Settings, configuration, and trust
• Configuration profiles, TOML settings, and scoped auth
• Environment variables
• Sandbox and overlayfs isolation
• Hooks and trust hooks
• Extensions and process protocol
• Skills
• Packages
• Memory
• Extended tool catalog
• Model Context Protocol (MCP) client
• Agent Client Protocol (ACP) mode
• Prompt templates and system prompt assembly
• Local / self-hosted models with llama.cpp
• Security
• Export and share
• Update safety

Quick start

First-run workflow

1. Install rpi:

   curl -fsSL https://raw.githubusercontent.com/0x8f701/rpi/master/install.sh | sh
   

   See install.md for Windows, pinned binary releases, manual archive verification, and rollback behavior.

2. Verify the binary:

   rpi --version
   

3. Configure one provider credential. For example:

   rpi login anthropic
   

   For non-interactive or CI use, set the provider-specific environment variable to a redacted credential value. Do not export placeholder values. For other providers, auth.json, models.json, and precedence rules, see authentication.md.

4. Run a non-interactive task to confirm the end-to-end path:

   rpi --print -m anthropic/claude-sonnet-4-5 "List the Rust files in this directory"
   

5. Start an interactive session:

   rpi -m anthropic/claude-sonnet-4-5
   

   The CLI opens the normal-screen inline TUI when both stdin and stdout are terminals; otherwise it uses the line REPL. See cli-modes.md for every flag, subcommand, and slash command.

Non-interactive print mode

rpi --print "Explain this crate" -m anthropic/claude-sonnet-4-5

# Or stream events as JSON lines for tooling
rpi --mode json -m openai/gpt-5.5 "List all unfinished task markers in src/"

Positional prompts initialize the interactive session on a terminal and select print mode when stdin or stdout is not a terminal. --listen is a separate headless Web-only service and rejects positional prompts; submit Web prompts through /web, /ws, or /rpc. Use --print when a script must be non-interactive:

rpi -m openai/gpt-5.5 "Review this repository"

Interactive session

rpi -m anthropic/claude-sonnet-4-5

• If both stdin and stdout are terminals, you get the normal-screen inline TUI.
• Otherwise you get the line REPL (> prompt).

In both modes you can type a message or use slash commands. Type /help for the 22 primary commands, including /workflow, the TUI-only /code-review and /btw overlays, and /live. Model and thinking-level switches work as slash commands in the line REPL; the TUI uses /model plus keybindings such as Ctrl+L and Ctrl+T.

Switch models and reasoning level

In the line REPL:

/model openai/gpt-5.5
/think high

From the shell you can set the initial model and thinking level:

rpi -m openai/gpt-5.5 --think high --print "Refactor this function"

See models.md for model-spec syntax and custom providers.

Manage sessions

# List native Pi sessions for the current directory
rpi sessions

# Resume the newest native Pi session for this directory
rpi --continue

# Resume a native or foreign session by path, exact id, or prefix
rpi --resume rollout-abc123.jsonl
rpi --resume abc123

In the interactive TUI and line REPL, /resume and /sessions open a current-cwd-scoped unified catalog with [source] badges for native Pi, OMP, Codex, Claude, Grok/Hyper, and Droid sessions. Selecting a foreign session imports it once into the effective native session root; later resumes reuse the converted file. Foreign source files cannot be renamed or deleted from the selector, but native and imported JSONL files can be. --continue stays native-only and resumes the newest native Pi session for the directory.

Sessions are stored as append-only JSONL files under <agent-dir>/sessions/. See cli-modes.md for path encoding, import details, and selector management rules.

Discover models

rpi models
rpi models claude
rpi models openai

The filter is case-sensitive and matches against provider name or model id.

Log in

rpi login
rpi login anthropic

login stores credentials in auth.json. logout removes them. For non-interactive configuration, use auth.json or environment variables (see authentication.md).

Export or share a session

# Export a session file to a self-contained HTML file
rpi export <agent-dir>/sessions/--<workspace>--/timestamp_id.jsonl

# Export the current branch as JSONL for later resume
rpi export session.jsonl --jsonl --output backup.jsonl

In the TUI or REPL, /share creates a secret GitHub gist via the gh CLI. See export-share.md for formats and sharing.

Use a local model

rpi llama configure http://127.0.0.1:8080
rpi -m llama.cpp/<model-id> --print "Hello"

See local-llama.md for router setup and GGUF downloads.

Manage packages

rpi install git:github.com/owner/pi-my-tools
rpi list
rpi update --extensions

Project packages need a trusted project. See settings-trust.md and packages.md.

Configure loaded resources

# Open an interactive selector for enabled extensions/skills/prompts/themes
rpi config

# Scope the selector to project-local settings
rpi config --local

Project scope is refused unless the project is trusted. See packages.md for the package/resource model.

Next steps

• Read cli-modes.md for the full command surface.
• Read settings-trust.md to configure defaults in settings.json.
• Read models.md to add custom providers or local models.

Installation

Supported platforms

The release workflow builds five native targets:

• aarch64-apple-darwin
• aarch64-unknown-linux-gnu (glibc 2.31 baseline, Ubuntu 20.04)
• x86_64-apple-darwin
• x86_64-pc-windows-msvc
• x86_64-unknown-linux-gnu (glibc 2.31 baseline)

Prebuilt binaries are published as GitHub Release assets named rpi-<version>-<target>.tar.gz (or .zip on Windows), alongside a SHA256SUMS manifest. Installation does not require Rust or a source checkout. The installers download, verify, and atomically activate the matching binary.

Or use the built-in updater after installation:

rpi update --self

Supported install paths

• Prebuilt binary installer — install.sh (macOS / Linux) or install.ps1 (Windows); recommended for users.
• Prebuilt GitHub Release asset — download the matching .tar.gz / .zip and SHA256SUMS, then verify and extract manually.
• Self-update — rpi update --self after the binary is installed.
• Source build — developer fallback requiring Rust 1.88 or later.

See update.md for release-check behavior and in-place update safety.

One-line installer

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/0x8f701/rpi/master/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/0x8f701/rpi/master/install.ps1 | iex

By default the installer resolves the latest published stable binary release. If the release does not contain the exact platform archive and SHA256SUMS, the installer fails without changing the existing installation.

Pin a version

Pin both the installer script and the requested release tag:

curl -fsSL https://raw.githubusercontent.com/0x8f701/rpi/v0.2.7/install.sh | bash -s -- --version v0.2.7

On Windows, download the script from the same tag before invoking it:

irm https://raw.githubusercontent.com/0x8f701/rpi/v0.2.7/install.ps1 -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File ./install.ps1 -Version v0.2.7

What the installer does

1. Detects the host OS/architecture.
2. Fetches release metadata from the GitHub API.
3. Downloads the archive and SHA256SUMS.
4. Verifies the archive digest.
5. Extracts the rpi / rpi.exe binary.
6. Smoke-tests the binary with --version.
7. Writes it to a content-addressed path under PI_HOME/downloads and atomically swaps PI_HOME/bin/rpi to that path on Unix. Windows atomically replaces PI_HOME/bin/rpi.exe because a running executable cannot be a symlink target.
8. Records the installed identity in PI_HOME/update-state.json.
9. On Unix, removes a legacy installer-managed PI_HOME/bin/pi symlink only when it still points at a previous installer-owned download path.

If any step fails, the installer rolls back the active symlink and leaves the previous install untouched.

When the install directory is not already on PATH, the Unix installer updates the detected shell profile and the Windows installer updates the user PATH. Open a new terminal before running rpi after such a change.

Installer environment variables

The token is sent only to the fixed GitHub API endpoint (https://api.github.com/repos/0x8f701/rpi/releases), never to release-asset hosts or a custom PI_UPDATE_BASE_URL endpoint. install.sh, install.ps1, and rpi update --self all apply the same scoping.

Developer source build

This is not the normal installation path. It requires Rust 1.88 or later.

git clone https://github.com/0x8f701/rpi.git
cd rpi
cargo install --path crates/pi-cli --locked --bin rpi
rpi --version

To build a distribution binary in-tree without installing into Cargo's bin directory:

cargo build --package pi-cli --bin rpi --profile release-dist --locked
./target/release-dist/rpi --version

The JSONL RPC control plane is the rpi rpc subcommand (≡ --mode rpc), so no companion binary is built or installed separately.

Verifying a downloaded release

After a release is published, replace <version> and <target> with an actual tag version and one of the supported target triples:

version="<version>"
target="x86_64-unknown-linux-gnu"
curl -fsSL -O "https://github.com/0x8f701/rpi/releases/download/v${version}/rpi-${version}-${target}.tar.gz"
curl -fsSL -O "https://github.com/0x8f701/rpi/releases/download/v${version}/SHA256SUMS"
sha256sum -c --ignore-missing SHA256SUMS

Directory layout

After installation:

$PI_HOME/   # default ~/.rpi on Unix, %USERPROFILE%\.rpi on Windows
├── bin/
│   └── rpi -> ../downloads/rpi-<version>-<os>-<arch>-sha256-<digest>
├── downloads/
│   └── rpi-<version>-<os>-<arch>-sha256-<digest>
└── update-state.json

On Windows the active executable is $PI_HOME/bin/rpi.exe rather than a symlink into downloads/.

On Unix, the installer creates the managed directories ($PI_HOME, bin/, downloads/) owner-only (0700) and writes update-state.json and the install lock as owner-only (0600), independent of the caller's umask. Installed binaries keep their executable mode (0755).

Runtime configuration and sessions are stored separately under <agent-dir>/ (the upstream pi layout, defaulting to ~/.pi/agent). The binary location and the agent directory are independent, so you can point PI_CODING_AGENT_DIR at a different config tree.

TUI and keybindings

The TUI is a normal-screen inline terminal interface built with crossterm and ratatui. It preserves terminal and tmux scrollback instead of switching to the alternate screen. It is selected when both stdin and stdout are terminals; otherwise the CLI uses print mode for positional prompts or the line REPL for a text session. The dispatch lives in crates/pi-cli/src/lib.rs:138-169.

Layout

 rpi (rs) · provider/model · /cwd
┌─────────────────────────────────────┐
│ Conversation                        │
│ ...                                 │
├─────────────────────────────────────┤
│ Message                             │
│ > type here                         │
├─────────────────────────────────────┤
│ Status line                         │
└─────────────────────────────────────┘

The conversation area keeps the most recent 4,000 transcript entries; when the limit is exceeded the oldest entries are dropped (MAX_TRANSCRIPT_LINES = 4_000 in crates/pi-cli/src/tui.rs:58, trimmed in tui.rs:1703). Tool execution is shown as status lines (· toolName(args) / └ ok / └ error).

When the transcript is empty, the welcome screen lists a few Recent sessions from the unified catalog, scoped to the current working directory. Each entry shows a [source] badge for native Pi, OMP, Codex, Claude, Grok/Hyper, or Droid sessions. Selecting a foreign session imports it once; subsequent resumes reuse the converted file under the effective native session root.

Built-in themes

Only two built-in palettes are always available:

• dark — the exact installed OMP v17.2.6 default titanium palette: electric blue chrome, green success/readouts, gold highlights, and dark titanium surfaces (DARK in crates/pi-cli/src/theme.rs).
• light — a high-contrast palette for light terminals (LIGHT in theme.rs).

The initial theme follows safe terminal background detection; dark terminals therefore use the OMP-default Titanium palette. It can be pinned in settings.json:

{
  "theme": "light"
}

Switch themes in the TUI with /theme, /theme next, /theme prev, or /theme <name>. The theme manager also live-reloads custom theme files and leaves the active palette unchanged when a reload fails (theme.rs:353).

Custom themes

Place JSON theme files in one of the theme directories:

• Global: <pi-dir>/themes/ (the .pi directory under the user's home directory: HOME on Unix, USERPROFILE on Windows, resolved by home_dir() in crates/pi-cli/src/tui.rs:4985)
• Project: <workspace>/.pi/themes/

Directory order is global-first, project-last (config_paths in crates/pi-cli/src/tui.rs:4971).

A theme file extends dark or light and overrides only the colors it specifies:

{
  "name": "solarized",
  "extends": "dark",
  "vars": {
    "blue": "#268bd2",
    "green": "#859900"
  },
  "colors": {
    "accent": "blue",
    "success": "green",
    "selectedBg": "#073642",
    "mdHeading": "#b58900",
    "syntaxKeyword": "blue",
    "toolDiffAdded": "green"
  }
}

extends must be "dark" or "light" (theme.rs:522). Role names may be camelCase (upstream) or snake_case (Rust-native); underscores and hyphens are ignored (theme.rs:567).

Semantic roles cover the complete transcript and editor surface (defined on Theme in theme.rs:41):

• Core: accent, border, borderAccent, borderMuted, success, error, warning, muted, dim, text, thinkingText
• Messages and tools: userMessageText, customMessageText, customMessageLabel, toolTitle, toolOutput
• Markdown: mdHeading, mdLink, mdLinkUrl, mdCode, mdCodeBlock, mdCodeBlockBorder, mdQuote, mdQuoteBorder, mdHr, mdListBullet
• Diffs and syntax: toolDiffAdded, toolDiffRemoved, toolDiffContext, syntaxComment, syntaxKeyword, syntaxFunction, syntaxVariable, syntaxString, syntaxNumber, syntaxType, syntaxOperator, syntaxPunctuation
• Thinking and modes: thinkingOff, thinkingMinimal, thinkingLow, thinkingMedium, thinkingHigh, thinkingXhigh, thinkingMax, bashMode
• Backgrounds: selectedBg, userMessageBg, customMessageBg, toolPendingBg, toolSuccessBg, toolErrorBg

Color values may be ratatui named colors (black, red, cyan, gray, darkgray, lightgreen, white, reset, ...) or hex #rrggbb / #rgb. Empty-string values resolve to the terminal default color for text, userMessageText, customMessageText, and toolTitle (theme.rs:100). Theme files are validated before loading; a malformed file is skipped with a diagnostic and the active theme is left unchanged.

Keybindings

The TUI maps incoming keys to stable actions through a KeyBindingsManager. Built-in defaults reproduce the original TUI behavior (default_bindings in crates/pi-cli/src/keybindings.rs:354). The dispatch layer never checks hard-coded chords; it resolves every key event to an Action (keybindings.rs:298).

Global editor and application defaults

Contextual selector defaults

Some chords are intentionally reused across mutually exclusive panels; they only dispatch when the matching panel is open (resolve_in in keybindings.rs:303, selector actions in keybindings.rs:323).

Saved session selector (/sessions, /resume with no argument):

Scoped model selector (/scoped-models):

Session tree / fork panel (/tree, /fork):

Up/Down/PageUp/PageDown move the selection in all selector and tree panels.

Custom keybindings

Place keybinding files in one of the keybinding paths:

• Global: <pi-dir>/keybindings.json (the .pi directory under the user's home directory)
• Project: <workspace>/.pi/keybindings.json

Project files overlay global files, which overlay built-in defaults (KeyBindingsManager::load in keybindings.rs:267). A file with any malformed chord, unknown action, or duplicate canonical chord is rejected in full with a diagnostic.

Two file formats are accepted:

Upstream action-to-chord object (preferred):

{
  "tui.input.submit": ["ctrl+enter"],
  "tui.input.newLine": ["shift+enter", "ctrl+j"],
  "app.exit": "ctrl+q"
}

Legacy pi-rs bindings array:

{
  "bindings": [
    { "chord": "ctrl+enter", "action": "editor_submit" },
    { "chord": "enter", "action": "editor_newline" },
    { "chord": "ctrl+q", "action": "quit" }
  ]
}

Overriding an action replaces all of its earlier chords, matching upstream behavior.

Valid actions are the stable IDs listed above. The canonical registry is VALID_ACTION_NAMES in keybindings.rs:177. Chords use +-separated modifiers and a key token. Modifiers are ctrl (alias control), alt (alias option), and shift. Key tokens include special names (enter, tab, esc, left, right, up, down, home, end, backspace, delete, space, pageup, pagedown, f1–f12) or a single Unicode scalar (a, /, 1).

Selectors, tree, fork, and dialogs

The TUI uses several modal page overlays inside the inline viewport. Typing filters the list, Enter confirms the selection, and Esc closes the overlay.

• Model selector (ctrl+l or /model with no argument): searchable list of configured providers and models (open_model_panel in tui.rs:1963).
• Thinking level selector (/settings → "Thinking level" or /theme not used): one entry per level (open_thinking_panel in tui.rs:1984).
• Settings panel (/settings): toggles thinking level, theme, and automatic compaction (open_settings_panel in tui.rs:2027).
• Trust panel (/trust): choose Trusted, Untrusted, or Ask for the current project (open_trust_panel in tui.rs:2080). Saved session selector (/sessions, /resume with no argument): unified catalog scoped to the current cwd, filter by name/path, sort by newest or name, rename (ctrl+r), and delete (ctrl+d) saved sessions. Rows show a [source] badge; foreign source files cannot be renamed or deleted, while native Pi sessions and already-imported conversions can be (handle_session_selector_key in tui.rs:2281).
• Scoped model selector (/scoped-models): enable/disable models for ctrl+p/ctrl+shift+p cycling, save the scope, and reorder enabled models (handle_scoped_model_selector_key in tui.rs:2387).
• Session tree (/tree): browse the branching message tree, fold/unfold, apply filters, and edit node labels (handle_tree_panel_key in tui.rs:2143).
• Fork panel (/fork): a tree filtered to user messages; selecting one and pressing Enter copies the active path up to that message into a new session (TreePanelMode::Fork in tree_panel.rs:9, open_fork_panel in tui.rs:2066).

Extension dialogs are raised when an extension requests interactive UI (ExtensionDialog in tui.rs:127). They include:

• Select: Up/Down to choose, Enter to accept, Esc to cancel.
• Confirm: arrow keys or Tab to swap the default; y/Y or n/N or Enter to accept; Esc to cancel.
• Input / Editor: full editor keys from the keybinding table, Enter (tui.input.submit) to accept, Esc to cancel.

(handle_extension_dialog_key in tui.rs:2576)

Terminal image behavior

Images are rendered only in the inline TUI. The line REPL and structured modes never receive image protocol bytes.

Protocol detection uses explicit environment evidence (detect_protocol in terminal_images.rs):

• Kitty: KITTY_WINDOW_ID, TERM=xterm-kitty, or TERM_PROGRAM equal to wezterm/ghostty. Under tmux, Kitty output is enabled only for tmux 3.3 or newer and every graphics APC is DCS-wrapped for passthrough. GNU Screen and older/unknown tmux versions fall back to metadata text.
• iTerm2: TERM_PROGRAM=iTerm.app and ITERM_SESSION_ID present.
• Sixel: TERM contains sixel. Sixel is detected for truthful diagnostics but is not emitted because the project does not yet include a bounded safe encoder; the TUI falls back to metadata text (supports_images in terminal_images.rs).

The TUI does not read stdin for an active graphics probe during startup, so terminal capability detection cannot consume user keystrokes. The implemented query contract uses Kitty's valid 1x1 RGB form and its response splitter preserves unrelated bytes, but the interactive startup path does not invoke it.

Image display settings come from terminal.showImages and terminal.imageWidthCells in settings.json (TerminalSettings in settings.rs; the default width is 60). Images are suppressed whenever an overlay such as a selector, tree, or dialog is open.

Layout and safety: the renderer decodes and validates the image, refuses empty data and payloads larger than the configured MAX_IMAGE_BYTES limit, clamps the layout to the viewport and imageWidthCells, preserves aspect ratio, and falls back to ordinary metadata when display is disabled or the protocol is unsupported.

Presentation: validated PNG payloads are transmitted in chunks of at most 4,096 base64 bytes with Kitty's transmit-only action (a=t) and separate pixel width/height controls (s=, v=). Image and placement IDs are explicit, non-zero, and randomized per renderer. Frame reconciliation deletes only the renderer-owned placement that moved or disappeared; cleanup deletes only its owned image IDs, never another application's placements. iTerm images retain the inline 1337 fallback with preserveAspectRatio=1.

Slash commands

The TUI and line REPL can execute the same built-ins, but /help, slash completion, and RPC discovery expose only the 22 commands in PRIMARY_COMMAND_NAMES (interactive_commands.rs). Prompt templates, dynamic skills, and extension commands remain executable through their namespaced paths.

Other built-ins such as /help, /new, /sessions, /tree, /todo, /snapcompact, /share, /copy, /login, /logout, /process, /theme, and /quit remain manually executable but are intentionally omitted from primary discovery.

/btw is read-only by default. Ctrl+T toggles edit/exec tools while the side agent is idle; Esc aborts a streaming turn or closes an idle overlay; Alt+R reforks from the current main leaf; Alt+N clears the side transcript. The overlay has its own editor, transcript, events, stream, and abort lifecycle. Closing it preserves the side controller for reopening, while TUI shutdown aborts and joins active side work.

/code-review displays staged and unstaged tracked changes against HEAD. Tab changes pane focus; j/k, arrows, and mouse clicks select hunks; c comments on the selected hunk; Space folds its inline review thread. Each thread appears after the complete hunk body with distinct comment/answer cards, and repeated agent progress messages collapse into one answer per exchange. Page keys and the mouse wheel scroll; tree clicks select or fold; Esc/q closes the page. Mouse capture is enabled only for this page and restored on every close or overlay transition.

/code-review accepts zero or exactly two arguments. Bare /code-review shows tracked HEAD→working-tree changes. /code-review <from> <to> resolves each ref (commit hash, branch, or tag) to a commit and renders the commit-to-commit diff labeled <from> → <to> in the panel title; working-tree changes are ignored. One argument or more than two is invalid — the page does not open and the status line shows Usage: /code-review [<from> <to>]. Pressing r refreshes the snapshot and preserves the selected revision pair.

Loop intervals accept positive bare seconds (/loop 300 check status) or compact s, m, h, and d units (/loop 3s echo hello, /loop 30m check deploy). Scheduled turns appear as Loop <id> · <cadence> system cards; the internal model instruction wrapper is not shown as a user message.

TUI vs REPL-only limitations

When stdout is not a TTY, main_run falls back to repl::interactive (lib.rs:142). The REPL shares the same slash-command catalog but lacks the TUI's modal page overlays:

• No modal pages: model, settings, trust, saved-session, scoped-model, session-tree, fork, /btw, and /code-review overlays are TUI-only. In the REPL, /scoped-models and /theme report that they require the TUI, /tree prints JSON, /fork with no argument prints candidate messages, and /model accepts a concrete spec.
• No configurable keybindings or themes: the REPL uses a fixed line-editing interface and ignores theme files.
• No terminal image rendering: image attachments are processed and sent to the model, but the REPL displays only text metadata.
• No interactive extension UI: the REPL is composed without the TUI's ExtensionUiAdapter (session_run.rs:491), so extension select/confirm/input dialogs cannot be answered interactively.

CLI modes and commands

rpi is a single binary that switches between non-interactive, headless, and interactive modes based on the flags you pass.

Top-level syntax

rpi [OPTIONS] [PROMPT]...

When no subcommand is given, a top-level run is selected by the flags and terminal:

1. --listen → headless Web-only service. It does not start or display a TUI or line REPL, ignores terminal interactivity, and remains alive until Ctrl-C/SIGTERM even when standard input is closed.
2. --mode json or --mode rpc → headless structured I/O.
3. -p / --print → print mode.
4. A non-empty positional prompt with non-terminal stdin or stdout → print mode.
5. Both stdin and stdout are terminals → TUI, with positional prompts submitted as initial turns.
6. Otherwise → line REPL, with positional prompts submitted as initial turns. Multiple positional [PROMPT] arguments are separate initial turns in JSON, print, TUI, and REPL modes. An empty prompt is skipped by structured modes and does not force print mode.

Top-level flags

Short aliases are normalized before clap parses: -v maps to --version, -xt to --exclude-tools, -nt to --no-tools, -nbt to --no-builtin-tools, -ne to --no-extensions, -ns to --no-skills, -np to --no-prompt-templates, and -nc to --no-context-files.

--provider requires --model; --api-key requires --model or --models. --continue, --resume, --session, --session-id, --fork, and --no-session are mutually exclusive.

For explicit LAN access — tokenless (no token, same-origin browser):

$ rpi --listen 0.0.0.0:8765 --listen-allow-insecure-remote

Open http://<host-lan-ip>:8765/web — or any hostname that routes to the host — from another machine; the browser auto-connects with no token. No --listen-advertised-origin is needed for ordinary /web, /ws, or /rpc: the browser's Origin authority must equal the HTTP Host (ordinary same-origin, which rejects unrelated cross-origin pages but is not authentication and not DNS-rebinding protection). This is plaintext and unauthenticated; use only on a network where passive observers are an accepted risk. To make the token mandatory, add --listen-token-file:

$ rpi --listen 0.0.0.0:8765 --listen-token-file <workspace>/rpi-token --listen-allow-insecure-remote

The token authenticates clients but does not encrypt traffic. rpi agent serve remains loopback-only. --listen-advertised-origin is only for collaboration links and the reachable URL printed at startup; loopback and specific binds advertise their bound address automatically, and a wildcard bind without it prints no reachable URL (ordinary web access still works via same-origin).

Subcommands

rpi models [FILTER]

List available models. Provider headers are printed in bold. The filter is case-sensitive and matches against provider name or model id.

rpi sessions

List native Pi v3 sessions for the configured working directory, newest first. Honors the global -C / --cwd flag in any position:

rpi --cwd /path sessions
rpi sessions -C /path

rpi import-session <SOURCE> <INPUT> [--output PATH]

Convert an external session to native Pi v3 JSONL.

Supported SOURCE values:

• pi
• omp
• codex
• claude
• grok
• droid

With --output the file is written to that path (or into the directory if the path is an existing directory). Without --output the file is placed under the per-cwd session directory and the command prints the emitted path and message count.

rpi login [PROVIDER] / rpi logout [PROVIDER]

Configure or remove stored credentials in auth.json. When run in an interactive terminal with no provider, a list of configured providers is shown. Outside a terminal the provider argument is required.

rpi reload

Validate the active settings/resource snapshot and print a JSON summary to stdout.

rpi export <SESSION_PATH> [--output PATH] [--jsonl]

Export a native Pi v3 session file to a self-contained HTML file (default) or to a current-branch JSONL file with --jsonl. No model, auth, or network access is required. Prints the output path to stdout.

rpi install <SOURCE> [--local] / rpi remove <SOURCE> [--local] / rpi list

Install, remove, or list local/git rpi packages. --local persists the package in the project's .pi/settings.json instead of the global agent settings. Project packages are only loaded when the project is trusted.

rpi config [-l|--local]

Configure enabled package resources (extensions, skills, prompts, themes) for global or project scope. In a terminal it opens an interactive selector; with non-TTY stdout it prints deterministic JSON. Project scope is refused unless the project is trusted.

rpi update [OPTIONS] [PACKAGE]

Update the managed installation, configured packages, or dynamic model catalogs.

• no arguments or --self: update the managed rpi installation.
• --extensions: reconcile every configured package.
• --self --extensions or --all: update packages, then update rpi.
• --models: refresh dynamic model catalogs.
• --extension SOURCE or positional PACKAGE: update one configured package.
• positional self or rpi: update the managed installation.
• --force: reinstall the selected self-update even when version and checksum match.

A package source cannot be combined with --self, --extensions, or --force.

rpi llama <COMMAND>

Manage a llama.cpp router and local GGUF downloads:

Interactive and service modes

1. Web-only listener — when --listen is passed. This service is headless and signal-driven; standard input is not an input or lifetime owner.
2. Headless JSON/RPC — when --mode json or --mode rpc is passed.
3. Print mode — when -p / --print is set, or a positional prompt is supplied while stdin or stdout is not a terminal.
4. TUI — when both stdin and stdout are terminals.
5. Line REPL — fallback for non-terminal text sessions.

All share the same session engine; only the input and rendering differ.

Print mode output

Print mode streams assistant text and tool activity to stdout:

· bash({command})
  └ ok

The result is...

A trailing newline is appended after the final assistant text.

Primary slash commands

/help, slash completion, and RPC command discovery expose exactly these 21 primary commands. Other built-ins remain manually executable where documented.

Frequently used hidden built-ins include /help, /new, /sessions, /tree, /todo, /login, /logout, /share, /copy, /process, /theme, /snapcompact (alias of /compact --snap), and /quit. They remain executable but do not appear in primary discovery.

/btw starts read-only. Ctrl+T toggles fresh workspace-scoped edit/exec tools when idle, Esc aborts a streaming side turn or closes an idle overlay, Alt+R reforks from the current main branch, and Alt+N clears the side transcript. Closing the overlay keeps its controller for reopening; leaving the TUI aborts and joins active side work. peek_main reads the current active main branch without writing to the main session.

/code-review uses direct bounded Git argv with pager, external diff, text conversion, configured filters, and interactive prompts disabled. It never sends repository content to a server. The page supports keyboard and mouse tree/hunk navigation, inline per-hunk comment threads after each complete hunk, fold/unfold controls, and one consolidated answer card per review exchange. Esc or q closes it and restores normal terminal mouse selection.

/code-review accepts zero or exactly two arguments. Bare /code-review shows tracked HEAD→working-tree staged and unstaged changes. /code-review <from> <to> resolves each ref — a commit hash, branch, or tag — to a commit and renders a commit-to-commit diff labeled <from> → <to> in the panel title; working-tree changes are ignored on this path. One argument or more than two is invalid: the panel does not open and the status line shows Usage: /code-review [<from> <to>]. Pressing r refreshes the snapshot while preserving the selected revision pair.

Loop intervals accept positive bare seconds (/loop 300 check status) or compact s, m, h, and d units (/loop 3s echo hello, /loop 30m check deploy). Values are honored exactly; zero and overflow are rejected.

REPL-only additions

The line REPL also accepts:

In the TUI, reasoning level and model cycling are controlled by keybindings instead. See tui.md.

TUI-only slash commands

TUI keybindings

The TUI uses the terminal's normal screen with inline redraws, preserving terminal and tmux scrollback. The transcript is above a composer and status line.

Type /hotkeys in either interactive mode to see a shortcut summary. Default bindings can be overridden with custom keybinding JSON files. See tui.md.

Session resume and import

Native sessions are Pi v3 JSONL files. Each line is an object with a type field. The active branch is reconstructed from parentId chains, so sessions can contain forks and the latest branch is followed on resume.

Session files live under:

<agent-dir>/sessions/--<workspace>--/<timestamp>_<id>.jsonl

<workspace> is the encoded cwd: the absolute path with leading separators removed and /, \, and : replaced by -.

The full-screen TUI selectors opened by /resume and /sessions, the line REPL bare /resume command, and the TUI startup Recent sessions list all draw from the same supported unified catalog. Automatic lists are scoped to the current working directory and display a [source] badge next to each row. Supported sources are native Pi (pi), OMP (omp), Codex (codex), Claude (claude), Grok/Hyper (grok/hyper), and Droid (droid).

--resume and /resume share this catalog. Native selections open the existing file without copying. Foreign selections are converted to Pi v3 once into the effective native session root, retain source lineage, and reuse that converted file on later resumes. In selectors, foreign source files are read-only: they cannot be renamed or deleted. Native Pi sessions and already-imported conversions are regular JSONL files under the session root and can be renamed or deleted from the selector. Only convertible user/assistant text messages are preserved during import; tool calls, reasoning, attachments, and branches are dropped.

--continue remains native-only and resumes the newest native Pi session for the directory.

Model spec syntax

• provider/id — explicit provider and model id.
• id — bare id matched across all providers.
• provider/id:level — explicit model plus thinking level suffix.
• id:level — bare id plus thinking level.

Resolution is case-insensitive. If the requested id is unknown but the provider is known, the CLI falls back to a synthetic custom-id model cloned from that provider's default template and prints a warning. This is useful with custom models.json entries.

Cancellation

• In print mode, Ctrl-C aborts the in-flight turn and the CLI exits.
• In the REPL, Ctrl-C aborts the current turn and returns to the prompt.
• In the TUI, Esc aborts the in-flight run.

Exit codes

• 0 — success (--help and --version also exit 0).
• 1 — any runtime/dispatch error. Errors are printed to stderr without secret values (crates/pi-cli/src/main.rs:24-27). Subcommands that fail (e.g. rpi export on a missing session) surface through this same path.
• 2 — argument/usage errors, reported by clap's parser (error.exit() in crates/pi-cli/src/args.rs:615-616).

There is no finer-grained exit-code table; all failure modes collapse to 1 (or 2 for a usage error before dispatch).

Related documentation

• authentication.md — env vars, auth.json, models.json
• models.md — model catalog, custom providers
• settings-trust.md — settings.json, config directory, trust
• tui.md — TUI themes and keybindings
• rpc-json.md — JSON/RPC event schema
• local-llama.md — local model setup
• packages.md — package manager details

Goals

A goal is a durable, session-scoped objective that describes why future turns may continue. It is deliberately separate from todos, plans, scheduled loops, and conversation messages: goals live in their own state machine with a lifecycle, an optional token budget, role-model pins, and a revisioned journal (crates/pi-coding/src/goal.rs).

The goal module only records state and returns a continuation decision — it never starts a turn. The Application layer decides whether to keep an active goal's work running and whether a goal turn should be queued or fired (crates/pi-coding/src/application.rs::activate_goal).

Lifecycle

A goal is one of (GoalLifecycle, goal.rs):

Only one goal is current at a time (GoalState.current). The state carries a revision counter; every transition is appended to the session journal as a typed event (GoalEvent), and the journal is replayed to reconstruct state on resume (goal_events_from_session_tree). Malformed or future goal entries fail closed during replay.

Usage

/goal show                       # inspect the current goal
/goal create <objective>         # set a goal (bare text is a create shorthand)
/goal create --tokens N <obj>    # set a goal with an explicit token budget
/goal pause                      # pause goal work
/goal resume                     # resume goal work
/goal complete                   # mark the objective done
/goal drop                       # abandon the objective
/goal pin <text>                 # add a role-model pin
/goal pins                       # list pins
/goal unpin <index>              # remove pin at 0-based index

Source: crates/pi-cli/src/goal_commands.rs (parse contract and executor), crates/pi-coding/src/application.rs (goal activation, pause, resume, complete, drop, pin, unpin).

Budget and usage

A goal may carry a tokenBudget (set with --tokens N; zero is rejected). Usage is tracked as GoalUsage { tokens_used, active_time_seconds }: the runtime accumulates model usage and active wall-clock time while the goal is active, and the goal continuation decision accounts for the budget. Without a budget the goal runs without a token ceiling. The /goal show summary renders active · 123/500 tokens · <objective> and includes time spent and pins (goal_commands.rs::format_goal_details).

Pins

A goal supports up to MAX_GOAL_PINS = 8 pins — short example or instruction strings (at most MAX_GOAL_PIN_CHARS = 200 characters each) shown verbatim in the goal turn's context as role models. Pins are managed with /goal pin <text>, /goal pins, and /goal unpin <index>.

Journal and invariants

Every goal event records both the transition and its resulting snapshot (GoalEventKind + goal), revisioned and validated against the previous state before it is appended (validate_replayed_transition). The typed event kinds (GoalEventKind in goal.rs:120-133):

Replay validation (validate_replayed_transition, goal.rs:880-993) rejects any event that follows a terminal lifecycle (except usage_updated), a resumed event after budget_exhausted pausing, completed/dropped with a pause reason or changed pins, and usage_updated deltas inconsistent with the previous snapshot. A created event after the first one, a fork_cloned whose source does not match the current goal, and malformed or future-version entries all fail closed.

• The journal is stored in the session file as a custom entry type pi.goal.event (GOAL_SESSION_CUSTOM_TYPE) at version GOAL_SESSION_ENTRY_VERSION = 1.
• Objective size is capped at MAX_GOAL_OBJECTIVE_BYTES = 64 KiB, well under the session record limit.
• A fork clones the current goal state; the cloned goal is validated so a forked journal cannot diverge (validate_fork_cloned).
• Goal usage is session-scoped: it accumulates across turns while active and is serialized with the goal, so a resumed session continues the same budget accounting.
• rewind (see session-recovery.md) treats goal journal entries as regular session entries; rewinding past a goal event rolls the goal back to the corresponding prior snapshot.

The goal tool

Orchestration children receive a goal tool exposing the same operations (create/show/pause/resume/complete/drop) so a delegated worker can manage its own durable goal. See orchestration.md.

Related documentation

• todos.md — the task-level plan, distinct from the goal
• orchestration.md — the goal tool in child sessions
• session-recovery.md — the goal appears in handoff envelopes (HandoffGoal in crates/pi-coding/src/handoff.rs)

Todos and the Todo DAG

Todos are the task-level plan of a session: an ordered set of phases, each holding tasks that can depend on other tasks, forming a directed acyclic graph (DAG). The todo tool (on by default; disable with settings.orchestration.todo = false) lets the model create, edit, and execute the plan in natural language, and the TUI renders it in a dedicated Todo DAG panel. Workflows plan into the same canonical structure and execute it with delegated subagents (see workflows.md).

Model

• TodoStatus — pending, in_progress, completed, abandoned (crates/pi-coding/src/todo.rs).
• TodoItem — id (stable task-<uuid>), content, status, depends_on (dependency task ids), ready, blocked_by (derived blocked-reasons with the blocking task's content and status), and an optional agent (a typed routing contract naming the agent that must execute the task).
• TodoPhase — name + tasks.
• TodoState — phases + storage (Session — persisted in the session file — or Memory).

Readiness is projected after every mutation: a pending/in_progress task is ready only when all of its depends_on tasks are completed or abandoned; otherwise it is blocked_by each unfinished dependency (project_readiness in todo.rs). Cycle detection rejects any mutation that would make the dependency graph cyclic (graph_contains_cycle), and phase names/task contents are normalized and validated before an operation commits (prepare_todo_phases).

todo tool operations

The tool is a single todo operation with these ops (TodoOp in todo.rs, serialized snake_case):

An init phase may carry agents[i] names parallel to items[i]: that task is routed to the named agent during DAG execution (validated against the agent catalog — unknown or disabled agent names fail actionably).

Results report the mutated phases, the list of tasks that just transitioned to completed (completedTasks), and a plain-text summary. The todo tool is transactional under orchestration: mutations run inside a gate with a check/commit pair so DAG execution and planning cannot race (TodoMutationTransaction).

/todo and the Todo DAG panel

In the TUI and REPL:

/todo            # open the Todo DAG panel (TUI) / print the plan (REPL)
/todo list       # print the plan
/todo markdown   # print the plan as Markdown checklists

Source: crates/pi-cli/src/interactive_commands.rs (/todo builtin), crates/pi-cli/src/todo_dag_panel.rs and crates/pi-cli/src/todo_dag_view.rs (panel), crates/pi-cli/src/todo_dag_panel.rs (TodoDagPanel).

The Todo DAG panel (TodoDagPanel in todo_dag_panel.rs) shows every DAG in the session: the main session's DAG plus one DAG per active workflow. Each DAG header renders the execution label and counts (✓ done · open · active · blocked); subagent rows under it show • <name> (<agent>) · <status> · <current task> with the owning todoTaskId. Keys: ↑/↓/j/k select a DAG or subagent row, Enter opens the detail page (task list with depends_on and blocked_by, plus linked jobs per task) or the subagent page (identity, type, status, owning DAG, linked todo task, current task summary, progress). Esc returns to the overview, Esc/q closes.

DAG execution

The DAG executes in two places:

• Orchestration: task calls pass a todoTaskId when the child owns a canonical Todo DAG item (orchestration/tools.rs); the runtime records the ownership on the job snapshot, and the panel deduplicates subagent rows against the DAG by task identity.
• Workflows: the supervisor arms execution over the committed plan (workflow/supervisor.rs::arm_plan_and_run); a workflow's Todo mutations never auto-arm — arming happens on Planning → Running and on resume. See workflows.md.

Steering and follow-up queues (/queue)

The session maintains two prompt queues with independent modes (QueueMode: all or one-at-a-time), configured by settings.steeringMode and settings.followUpMode (default all):

• steer — an interrupting prompt delivered into the active turn.
• follow-up — a prompt queued for the next turn.

When a mode is one-at-a-time, only one queued message of that kind is delivered at a time; the rest stay pending.

/queue            # show pending steering/follow-up prompts
/queue cancel     # clear both queues

Source: crates/pi-cli/src/interactive_commands.rs (/queue builtin), crates/pi-coding/src/application.rs (queued_messages/drain_queued_messages), crates/pi-coding/src/session.rs (queue storage). The RPC surface exposes set_steering_mode/set_follow_up_mode and prompt with streamingBehavior "steer"/"followUp" (see rpc-json.md).

RPC

set_todos replaces the session's phases ({"type":"set_todos","phases":[...]}); todo_updated events announce changes. See rpc-json.md.

Invariants

• The Todo DAG is always acyclic; cyclic mutations are rejected.
• Readiness is derived, never stored: ready/blocked_by are recomputed from depends_on + statuses after every mutation.
• completed transitions are reported exactly once per task per mutation (completion_transitions compares before/after).
• A re-init that matches the current plan is a no-op on ids/dependencies — stable todoTaskIds survive re-planning of an identical plan.
• The todo tool is available to orchestration children by default and is never removed by role ceilings (orchestration plumbing).

Related documentation

• workflows.md — workflow planning/execution over the DAG
• orchestration.md — todoTaskId ownership and jobs
• goals.md — the goal (why), distinct from todos (what)
• rpc-json.md — set_todos, todo_updated, steering

Orchestration: subagents, jobs, and IRC

The orchestration runtime (crates/pi-coding/src/orchestration/) lets the main session delegate work to child coding sessions ("subagents"), supervise them as jobs, and coordinate between them with IRC-style mailbox messages. It powers the task, hub, yield, and goal tools, the workflow executor (see workflows.md), and the TUI's agents panel and Todo DAG view.

Enabling

Orchestration is opt-in. Set settings.orchestration.tasks = true (the task tool gate; orchestration_enabled in crates/pi-coding/src/settings.rs:1403-1409). The todo tool is on by default and the process tool is gated by orchestration.process.

{
  "orchestration": { "tasks": true }
}

The workflow runtime requires orchestration and gates it separately; see workflows.md for the full orchestration settings block.

Agent catalog

Agents are Markdown definitions with YAML frontmatter, discovered from <agent-dir>/agents/*.md and (when the project is trusted) <workspace>/.pi/agents/*.md (AgentCatalog::discover in orchestration/definitions.rs:138). The bundled task and researcher agents are always available; user definitions win over bundled ones.

Frontmatter fields (AgentDefinition in orchestration/definitions.rs:66-88):

Model resolution precedence: settings override → first matching definition pattern → parent session model (resolve_agent_model, orchestration/definitions.rs:318-375). Settings entries can disable an agent (settings.agents.<name>.enabled = false; /agents manages these), and a child that declares tools outside the supported set is not blocked: unknown declared tools are silently ignored (OMP-compatible) with a single deduped warning, and an invalid model makes the agent unavailable with an actionable error.

The task tool

task starts one or more independent child coding-session jobs and returns immediately with stable job and agent ids; supervision happens through hub (orchestration/tools.rs:39-67). A child that owns a canonical Todo DAG item receives that item's stable id as todoTaskId.

task agent=researcher task="Study the persistence layer" todoTaskId=task-abc
task tasks=[{name: "w1", task: "Draft API"}, {name: "w2", task: "Write tests"}]

Delegation intent is also recognized from the main prompt: an English delegation verb ("Have researcher study this") or a conservative CJK construction ("你让researcher仔细调研…") escalates to an exact trusted agent name; informational mentions do not. Ambiguous mentions with explicit delegation intent are errors (actionable, naming the candidates).

The matcher is exact-token based (runtime.rs:4936-4977): the English token set is have, ask, tell, get, let, make, please, delegate, assign, spawn, run, send, kick, dispatch (ENGLISH_DELEGATION_VERBS, runtime.rs:4939-4941), matched as whole NFKC-lowercased tokens — so researchers never matches researcher. The CJK token set is 让, 请, 叫, 派, 安排, 委托, 交给 (CJK_DELEGATION_TOKENS, runtime.rs:4948), matched conservatively: the token must directly precede the agent name with no intervening tokenizer boundary (a CJK script run like 你让researcher), using the same word-boundary logic the selector applies (selector.rs:1107-1111). A recognized verb or CJK construction plus an unambiguous agent-name mention selects that agent; multiple distinct agent names with delegation intent is an error listing the candidates.

Jobs and supervision

Every delegated child runs as a job (JobSnapshot in orchestration/runtime.rs): queued → running → completed | failed | cancelled | aborted, with created_at/started_at/finished_at, a description, an optional todoTaskId, a redacted result/error, and a softBudgetExhausted marker.

• Concurrency: at most orchestration.maxConcurrency children run at once (default 8, semaphore-bounded); recursion depth is bounded by maxRecursionDepth (default 8).
• Job retention: settled jobs and their artifact files (<agent-id>-<job-id>.md outputs, <agent-id>-<job-id>.history.json transcripts) are retained up to DEFAULT_MAX_RETAINED_JOBS = 256 for DEFAULT_RETAINED_JOB_TTL_SECS = 24h, then pruned (JobRetention in orchestration/runtime.rs:32-33).
• Idle parking: idle non-main agents park after DEFAULT_IDLE_TTL_SECS = 300s and are revived on demand (schedule_idle_park).
• Soft budgets (JobSoftBudget in orchestration/runtime.rs:154-166, settings orchestration.softBudget): maxRequests, maxTokens, and yieldAfter are all optional and default to unlimited (run-to-completion behavior). When a configured limit is reached the child is not failed: its run stops cleanly after the current turn, the job settles Completed with the partial result, and both TaskResult and JobSnapshot carry softBudgetExhausted: true so the parent can decide whether to continue the child.
• Contract bounds: maxTurns, maxToolCalls, and timeoutSecs from the agent definition stop the child cleanly with a clear reason; a child that exceeds its timeout contract after an abort is reported.
• Durable orchestration: child sessions are recorded to their own JSONL transcripts under the durable child root; the runtime persists agent snapshots, mailboxes, and job state to a sidecar so a restarted session revives queued children and re-delivers their mailboxes (orchestration/persistence.rs).

The child's tool set is assembled per role: coding tools filtered by the capability ceiling and disallowedTools, plus orchestration plumbing. The child also receives the yield tool, the hub tool, and the goal tool.

The hub tool

hub coordinates with Main and child peers (orchestration/tools.rs:70-103):

• hub send <to> <message> — deliver a mailbox message (subagent ⇄ subagent included). Delivery is durable: the message is committed to the recipient's mailbox before any revival claim, and the bounded delivered-message log (cap 200) keeps messages visible to the workflow page's Recent IRC even after consumption.
• hub wait [from] [timeoutMs] — block until a message arrives; registered waiters make the delivery bridge defer matching sends so the waiter drains them durably (MessageWaiter, RAII-unregistered on every return path).
• hub inbox [peek] — read queued messages without necessarily consuming.
• hub list — refresh the peer roster (spawn-time snapshot with <peer_roster> + <truncated /> bounds).
• hub read_history <agent> [lines] — rendered transcript of a peer (default 50 lines, hard max 200, 32 KiB byte cap).
• hub jobs / hub cancel / hub wait — supervise child task jobs.

The roster a child sees is a spawn-time snapshot: hub list refreshes state and hub send addresses exact ids.

The yield tool

yield is the explicit-delivery protocol for child sessions (orchestration/tools.rs:104-119, YieldState in orchestration/runtime.rs:791-836): a child calls it exactly once, passing the full final deliverable as text; that payload becomes the job's delivered output and the child's run terminates. It is wired to per-run delivery state the run loop reads when the child settles, so the payload lands in TaskResult.output. A child that exits without calling yield settles with its natural final text plus the marker:

SYSTEM WARNING: Subagent exited without calling yield

The goal tool

Children receive the goal tool so a delegated worker can create, show, pause, resume, complete, or drop a session goal — the same durable goal state machine documented in goals.md. Orchestration plumbing means role filters never remove it.

Live progress and activity

The runtime publishes ApplicationEvents (agent_start, agent_settled, job_*, todo_updated, orchestration mailbox messages) that drive the TUI agents panel and the workflow page. Each agent has a live AgentSnapshot (display name, status, current task summary, todo ownership) and a bounded per-agent activity feed; the workflow detail merges delegated task lifecycle entries with IRC messages per agent (workflow/detail.rs). Everything shown to the UI is redacted.

Concurrency gates and settings

• orchestration.maxConcurrency (default 8) — child semaphore; a global workflow-scoped gate can additionally limit workflow children.
• orchestration.maxRecursionDepth (default 8) — the task tool is only offered to a child while depth < maxRecursionDepth.
• orchestration.mailboxCapacity (default 1000) — per-agent mailbox bound.
• orchestration.maxToolsPerAgent (default 16) — tool-count ceiling for a child's coding tools.
• orchestration.sandboxed (default false) — run child process spawns in the Linux filesystem sandbox.
• orchestration.softBudget — per-child soft budget (see above).

All bounds are validated in OrchestrationConfig::validate (orchestration/runtime.rs:368-392) and at settings load time (settings.rs:2674-2697).

Invariants

• A child job is never failed by a soft budget — it settles Completed with the partial result and the softBudgetExhausted marker.
• yield delivers exactly once; a missing yield is observable to the parent via MISSING_YIELD_WARNING.
• Messages are durably committed to the mailbox before any revival claim, so a restart cannot lose a delivered IRC message.
• Mailbox waits are RAII: every return path (timeout, abort, shutdown, drop) unregisters the waiter so no stale claim strands a message.
• Role ceilings only ever remove tools; orchestration plumbing (todo/process/task/hub/goal) is preserved so restricted roles can still delegate and be supervised.

Related documentation

• workflows.md — workflow lifecycle on top of this runtime
• todos.md — the Todo DAG and its execution
• goals.md — the durable goal state machine
• skills.md — agent definition format details

Isolated concurrent workflows

A workflow is a durable, isolated, self-contained run of the agent that plans an objective into a canonical Todo DAG and then executes that DAG with delegated subagents. Workflows are managed with /workflow and rendered live in a dedicated TUI page (subagents, tasks, and IRC). The durable lifecycle lives in crates/pi-coding/src/workflow/ (manager, store, supervisor) and the isolation backends in crates/pi-coding/src/workflow_worktree/ (git worktrees) and crates/pi-coding/src/workflow_worktree/overlay.rs (overlayfs).

Lifecycle

A workflow moves through a strict status machine (WorkflowStatus in crates/pi-coding/src/workflow/mod.rs:53-64):

Lifecycle transitions are validated in two places: the manager rejects actions that are not allowed for the current status (ensure_allowed in workflow/manager.rs), and the supervisor projects only legal transitions back (validate_status). Pause is legal from queued/planning/running; resume is legal from paused/planning/running; cancel is legal from any non-terminal status; integrate is legal from completed/paused/conflicted (manager) and completes from completed/conflicted/failed (supervisor).

Transition table with reasons

Every transition below is enforced at workflow/manager.rs:517-531 (action gates and runtime projection) and workflow/supervisor.rs:652-716 (supervisor-side handling); the reasons are the conditions that make each transition legal.

The supervisor may also project queued → completed/failed (restored terminal outcomes) and planning → completed/failed; terminal statuses (completed/failed/cancelled/conflicted) and paused/integrating can never be re-entered from a runtime projection — a stale or regressing projection is rejected (validate_runtime_projection).

/workflow command

Canonical usage (WORKFLOW_USAGE in crates/pi-cli/src/workflow_commands/mod.rs:14-15):

/workflow [list|show [id|name]|create <objective>|create <name> <objective>|pause|resume|cancel|integrate|remove]

• Bare /workflow opens the dedicated workflows page in the TUI.
• /workflow list lists workflows (status · name · id · objective).
• /workflow show [id|name] shows one workflow's detail.
• /workflow create <name> <objective> (or a single argument used as both) creates a workflow; the newly created workflow becomes the selection.
• /workflow pause|resume|cancel|integrate|remove [id|name] operate on the selected workflow, or on the named one. Selectors accept the workflow id or an exact name.

Source: crates/pi-cli/src/workflow_commands/mod.rs (parse contract and executor), crates/pi-cli/src/workflow_rpc.rs (RPC surface).

The RPC surface (WorkflowRpcCommand in workflow_rpc.rs:87-130) mirrors the slash command on the JSONL control plane (see rpc-json.md):

Wire snapshots project the durable WorkflowSnapshot (status, integration none/applied:<commit>/conflicted:<paths>, failure message) and workflow_updated / workflow_status_changed / workflow_removed events stream status changes (workflow_rpc.rs:219-257).

Isolation backends

Each workflow runs in its own checkout of the source tree. The backend is selected by settings.orchestration.isolation (WorkflowIsolationSetting in crates/pi-coding/src/settings.rs:283-298):

The overlayfs backend tries, in order, kernel overlay (mount -t overlay), fuse-overlayfs (unprivileged FUSE daemon), then recursive copy — the first candidate that succeeds wins, and the chosen backend is persisted per workflow so a restored workflow re-mounts exactly what it had (default_backend_candidates in workflow_worktree/overlay.rs:68-75, crates/pi-coding/src/isolate.rs).

Ownership is strict: every operation verifies that the live checkout exactly matches the recorded identity (source root, common git dir, branch, HEAD commit) before touching anything, and removal/prune only ever touch manager-owned identities (WorktreeError::OwnershipMismatch). The managed root must not be inside the source worktree, and the source base must be clean before integration (DirtyBase is refused).

Integration strategies (IntegrateStrategy in workflow_worktree/mod.rs:197-206): merge fast-forwards when possible and otherwise creates a merge commit; rebase replays workflow commits onto the current source HEAD. The outcome is Applied { strategy, result_commit } or Conflicted { conflicts } — recorded on the durable snapshot as WorkflowIntegration::None | Applied | Conflicted (workflow/manager.rs:23-28).

Planning phase

A workflow starts in queued, then moves to planning: the supervisor agent (running in the workflow's own Application context) receives a bounded planning prompt (WorkflowSupervisorContract in workflow/supervisor.rs). The planning contract requires the model to create the complete canonical Todo DAG exactly once with the todo tool and then stop — no delegation, no file edits, no waiting on jobs during planning. Explicit agent references in the objective are validated against the workflow agent catalog before any planning prompt runs (validate_delegation_agents).

Planning is bounded so a correcting model can never hold the workflow in Planning forever:

• PLANNING_MAX_TURNS = 8 assistant turns (workflow/supervisor.rs:35).
• PLANNING_MAX_TOOL_CALLS = 16 — cap on Todo/tool calls in one planning prompt (workflow/supervisor.rs:37).
• PLANNING_DEFAULT_DEADLINE = 90 s — one wall-clock budget for the whole planning turn, measured from a single pinned sleep (a provider streaming keepalives can never stretch it into a deadline-of-silence) (workflow/supervisor.rs:41, 1051-1061).
• PLANNING_IDENTICAL_FAILED_OP_LIMIT = 3 — identical failed Todo operations with no Todo-state change terminate planning (workflow/supervisor.rs:44).
• PLANNING_CORRECTIONS_WITHOUT_PROGRESS_LIMIT = 6 — semantic non-progress detection on the canonical Todo state (workflow/supervisor.rs:46-48).
• A replan prompt gives a model that answered the first turn with plain text one chance to build the plan.

The outcome is one of Completed, PlanCommitted (plan accepted on the first successful todo init, even while the model still has turns to emit), PlanBudgetReached { reason }, or TimedOut. A committed plan (or a budget stop with tasks present) preserves the plan and transitions to running immediately (arm_plan_and_run / preserve_plan_and_run).

The supervisor's own planning turn is projected live into the workflow page as a bounded activity feed (thinking chunks, tool calls, IRC progress) so planning never reads as a static spinner (WorkflowSupervisorActivity, workflow/supervisor.rs:85-110; planning_started_at_ms tracks the phase).

Execution phase

running re-arms Todo DAG execution over the committed plan: each task in the canonical Todo state is executed by a delegated subagent (see orchestration.md), with todoTaskId linking each job to its task. The workflow's Todo mutations never auto-arm execution (workflow/supervisor.rs:966-984); arming is explicit on the Planning → Running transition and on resume of a restored running workflow, so a parked DAG with open tasks is an actively worked workflow, not a Planning one. Restored workflows never come back frozen: restored Queued/Planning resume the planning flow, restored Running re-arms execution, restored Paused stays paused until an explicit resume (WorkflowSupervisor::continue).

When the DAG settles (all tasks completed or abandoned), the supervisor projection moves the workflow to completed and the manager auto-integrates when the status ends completed with no prior integration (workflow/manager.rs:372-377, 439-444). Integration is also available manually with /workflow integrate.

Live detail and workflow panel

The workflow page (crates/pi-cli/src/workflow_panel.rs) renders a live, redacted projection of each workflow (WorkflowRuntimeDetail in workflow/detail.rs:17-36):

• todo — the canonical Todo DAG.
• supervisor — the planning/running supervisor row with its own activity feed; during planning the (idle at the orchestration layer) supervisor reads as actively planning.
• subagents — one row per delegated worker: display name, agent type, status, current task summary, owning todoTaskId, and a bounded per-agent activity feed (task lifecycle entries + IRC messages the agent sent or received, newest-last).
• jobs — delegated orchestration jobs with their todo ownership.
• irc — the workflow's recent IRC (subagent ⇄ subagent included), deduped by message id and capped at 50 (RECENT_IRC_LIMIT).

Everything in the live view is redacted (paths, ids, tokens), and a terminal durable status always wins over a stale live projection — a Conflicted integration that lands after the supervisor projected Completed is shown as Conflicted (workflow/detail.rs:251-268). The durable workflow record never persists activity; the activity feed is live-only.

The supervisor settles from the canonical Todo state and publishes WorkflowEvents (StatusChanged, Updated, Removed) through the WorkflowManager, which persists durable snapshots to the workflow store (workflow/store.rs) and restores them on restart (WorkflowManager::reload).

Settings

{
  "orchestration": {
    "tasks": false,
    "todo": true,
    "maxConcurrency": 8,
    "maxRecursionDepth": 8,
    "mailboxCapacity": 1000,
    "maxToolsPerAgent": 16,
    "isolation": "worktree",
    "sandboxed": false,
    "softBudget": { "maxRequests": null, "maxTokens": null, "yieldAfter": null }
  }
}

• tasks — enables the orchestration task tool (default false).
• todo — the todo tool is on by default; false opts out (settings.rs:1411-1420).
• maxConcurrency — max parallel child jobs (default 8, bounds 1..=64).
• maxRecursionDepth — max nested delegation depth (default 8, max 16).
• mailboxCapacity — per-agent message mailbox (default 1000, max 10000).
• maxToolsPerAgent — tool ceiling per child (default 16, max 64).
• isolation — worktree (default), overlayfs, or none; unknown values fail deserialization (fail-closed).
• sandboxed — when true, orchestration subagent children run their process spawns (the bash tool) inside the Linux filesystem sandbox (workspace + agent dir + sandbox.allowedPaths visible; deny-by-default otherwise). See sandbox-isolation.md.
• softBudget — per-child job soft budget: maxRequests (LLM turns), maxTokens (cumulative usage), yieldAfter (return control to the parent after N requests regardless of remaining budget). A reached limit settles the child Completed with softBudgetExhausted: true, never failed. See orchestration.md.

Validation: maxConcurrency must be 1..=64, maxRecursionDepth at most 16, mailboxCapacity 1..=10000, maxToolsPerAgent 1..=64, and soft-budget knobs must be positive when set (settings.rs:2674-2697).

Invariants

• Workflows never execute without a committed plan: running implies the Todo DAG was armed by the supervisor.
• Planning is always bounded: 8 turns, 6 non-progress corrections, and a wall-clock deadline; a stuck provider cannot hold a workflow in Planning forever.
• Isolation is ownership-checked: every backend operation verifies the exact recorded identity before mutating; foreign checkouts fail closed.
• Integration refuses dirty sources and dirty workflows (DirtyBase / DirtyWorktree), and overlayfs integration is last-writer-wins by design.
• The durable snapshot is authoritative for terminal outcomes; the live projection may never mask a Conflicted or Failed state.
• rewind is refused while any workflow is active (see session-recovery.md).

Related documentation

• orchestration.md — the subagent/job runtime that executes the DAG
• todos.md — the canonical Todo DAG the workflow plans and executes
• sandbox-isolation.md — filesystem sandbox and overlayfs backends
• cli-modes.md — /workflow in the slash-command surface

Session recovery: rewind, checkpoints, handoffs, and TTL

This page covers the session-level recovery and hygiene features: rewinding to an earlier point in the journal, named checkpoints, deterministic snap compaction, handoff summaries, doom-loop recovery, and startup TTL pruning of old session files.

/rewind and /checkpoint

/rewind                       # list entry indices and checkpoints to pick from
/rewind <entry-index>         # roll the session back to before that entry
/rewind <checkpoint-name>     # roll back to the named checkpoint
/checkpoint <name>            # mark the current position as a named rewind target

/rewind truncates the session journal back to a target and archives the dropped tail to a sidecar (the session store keeps every file; nothing is lost). The bare command lists the last 20 records with first-line previews, annotating checkpoints with the entry they target. /checkpoint <name> marks the current position so /rewind <name> can return to it later; a checkpoint named like a number is unreachable by design (numbers always parse as entry indices).

Sources: crates/pi-cli/src/interactive_commands.rs (parse_rewind_invocation, format_rewind_list, format_rewind_outcome), crates/pi-coding/src/application.rs (rewind, set_checkpoint, rewind_preview).

Safety: rewinding is refused while any orchestration job is queued or running, while any workflow is active, or while bash is still executing — truncating the journal under live work would orphan running jobs and corrupt the state those jobs keep reading. The active turn is drained first so the checks observe post-turn state, and the refusal message names the count of live jobs and suggests orchestration /queue cancel or workflow /workflow cancel (rewind_refusal in application.rs:2250-2264).

/snapcompact and /compact --snap

/snapcompact                  # deterministic archive, no LLM call
/compact --snap               # same (trailing text after --snap is ignored)
/compact [instructions]       # legacy LLM summarization path

compact_snap (in application.rs:2077-2080) replaces older turns with a deterministic statistics block — per message-type counts, total archived characters, timestamp span, sorted unique tool names, and a bounded list of user-ask first lines (build_snapcompact_summary in crates/pi-coding/src/compaction.rs:471) — and preserves the original entries in a .snapcompact-<timestamp>.jsonl sidecar. The cut point never splits a turn (find_snap_cut_point). Useless tool results (empty or duplicate error text) are elided with a note.

The LLM path uses the structured checkpoint summary prompt (SUMMARIZATION_PROMPT in compaction.rs:64-65) and rebuilds the view as a CompactionSummary message followed by the recent entries (apply_checkpoint). Automatic compaction triggers on context threshold (should_compact with compaction.enabled/reserveTokens/ keepRecentTokens); see settings-trust.md.

/handoff

/handoff                      # deterministic envelope (copied to clipboard)
/handoff --prose              # envelope + one bounded prose paragraph

A handoff is a concise, structured summary of the current session — what was done (recent user asks), current state (active goal, todo counts, running orchestration jobs), environment (cwd, git branch and dirtiness, model), and deterministic next-step hints. The envelope is built entirely from session state with no model call (handoff_envelope in crates/pi-coding/src/handoff.rs:226); --prose adds one paragraph from the existing summarization path, bounded to a single provider call with a hard 60-second timeout and a 600-token reserve (HANDOFF_SUMMARIZE_TIMEOUT, HANDOFF_PROSE_RESERVE_TOKENS).

The rendered block (# Handoff) is copyable plain text, safe to paste into a fresh session. Everything in it is redacted for credential-shaped text, and only queued/running jobs appear (active_handoff_jobs). Hints are capped at 4 (HANDOFF_MAX_NEXT_STEP_HINTS).

Source: crates/pi-cli/src/interactive_commands.rs (/handoff builtin), crates/pi-coding/src/handoff.rs.

Doom-loop recovery

The session turn loop detects a doom loop — the same tool failing with the same error prefix DOOM_LOOP_THRESHOLD = 3 consecutive times in one turn — and stops the turn with an actionable message instead of letting the model retry the same failing call forever (DoomLoopTracker in crates/pi-coding/src/session.rs:189-232, doom_loop_recovery at session.rs:4553). Error prefixes are fingerprinted at DOOM_LOOP_ERROR_PREFIX_CHARS = 80 characters; transient markers ("timed out", network blips) never count toward the threshold. Once tripped, every further tool outcome in the turn terminates with the same message so a parallel batch cannot escape the stop, and the turn errors out with it.

Session TTL cleanup

At startup, rpi prunes old native session files:

• Default age: DEFAULT_SESSION_TTL_DAYS = 30; override with settings.sessionTtlDays (must be > 0).
• Files modified within SESSION_ACTIVE_GRACE = 1 hour are treated as possibly active and never pruned (the native store has no lock files).
• Pruning touches only the native pi session tree (files at up to two directory levels below a root); foreign sources (codex/claude/grok) live in separate roots and are never walked.
• Never pruned: the current session's file, the live run's directory, symlinks (never followed or deleted), and files with future/implausible mtimes (PRUNE_MTIME_FLOOR_SECS).

Source: crates/pi-coding/src/session_store.rs (prune_expired_sessions, session_file_expired). The recorder self-heals if a prune removed its (as yet empty) per-cwd directory before the first flush.

/fresh

/fresh (alias for /new) archives the current session in place and starts a clean session — the session store keeps every file, so the old recorder stays on disk. See export-share.md.

Invariants

• Rewind never loses data: the dropped tail is archived, and rewinding is refused while any live work (jobs, workflows, bash) could be orphaned.
• Snapcompact never calls the provider and never splits a turn; the original entries survive in a sidecar.
• Handoff envelopes are deterministic and redacted; prose is a single bounded provider call.
• Doom-loop recovery is per-turn and transparent (transient errors never count), and it cannot be escaped by a parallel tool batch.
• TTL pruning is conservative: grace-window, current-session, foreign, symlinked, and clock-skewed files are never deleted.

Related documentation

• export-share.md — /export, /dump, /share --encrypt, /fresh
• settings-trust.md — compaction, sessionTtlDays settings
• goals.md — goal journal entries participate in rewind

Live voice (/live)

/live is a minimal hold-to-talk realtime voice mode: microphone capture → speech-to-text → composer draft (crates/pi-coding/src/live.rs). It is modeled on Hyper's Codex Live but deliberately simple: press to record, release to transcribe, and the final whole-utterance transcript lands in the composer draft for the user to review before pressing Enter. It is never auto-submitted.

Configuration

/live requires explicit configuration in settings.json (LiveRuntimeSettings in crates/pi-coding/src/settings.rs:425-429):

{
  "live": {
    "enabled": true,
    "sttBaseUrl": "https://your-whisper-host",
    "sttApiKey": "<secret>",
    "sttModel": "whisper-1",
    "language": null,
    "allowInsecure": false
  }
}

Validation (validate_live_settings in live.rs:97-129):

• ws:///wss:// URLs are always rejected — /live speaks HTTP multipart to {base}/v1/audio/transcriptions, not WebSocket.
• Plaintext http:// is refused unless allowInsecure is explicitly true.
• Errors name the exact Settings.live.* key to fix.

Usage

In the TUI, /live opens a hold-to-talk session:

• Press (hold key) starts recording; a new press while recording or transcribing supersedes the previous session (its buffer is discarded so the old transcript cannot land in a new target).
• Release stops capture and transcribes the utterance.
• A 10-second no-speech watchdog stops capture with guidance; an utterance shorter than 250 ms is discarded as accidental; Esc/teardown aborts without transcribing.

Capture is mono 16 kHz i16 PCM (SAMPLE_RATE = 16_000), held in a bounded backlog (30 s of audio), and the STT request runs with a 30-second client timeout. The final transcript is delivered as a Transcript event into the composer draft — the user reviews and presses Enter.

Microphone backend

Microphone capture uses cpal behind the live-capture feature. A build without it fails with an actionable error:

Microphone capture is not compiled into this build. Rebuild with
--features pi-coding/live-capture (requires cpal and, on Linux,
libasound2-dev), or use a build that ships it

(open_capture in live.rs:189-201).

Delegation bridge

Hyper's Codex Live receives server-side delegation.created events; rpi's generic STT endpoint never emits them, so the bridge detects delegation intent client-side from the transcript: a coding verb (implement/fix/add/ test/refactor/write/create/update/change/remove/delete/debug/repair/migrate…) paired with a code-domain signal (file path, extension, or code word) (is_delegation_candidate in live.rs:681). The signal sets are exact (live.rs:681-699): DELEGATION_VERBS = implement, fix, add, test, refactor, write, create, update, change, remove, delete, debug, repair, migrate, optimize, rewrite, extend, port; DELEGATION_CODE_WORDS covers code-domain nouns (function, class, struct, module, api, endpoint, cli, bug, test, config, …); DELEGATION_EXTENSIONS covers .rs, .py, .ts, .js, .go, .c, .md, .sh, .json, .toml, … — a bare config/path word or a slash-containing token also counts as a code signal. The verb must appear as a whole word (boundary matched) and the code signal must not be the verb itself (has_code_signal, live.rs:730-739). The TUI offers the draft with a ⟦delegate⟧ hint and submits it through the standard prompt path — the delegation is an ordinary agent turn: no separate task queue, and the reply merges into the transcript like any other turn.

Invariants

• Transcripts are never auto-submitted: every utterance lands in the composer for review.
• STT credentials never leave the machine unencrypted: plaintext endpoints are refused unless allowInsecure is explicit, and server-echoed secrets are scrubbed from errors.
• Capture is bounded: audio backlog, no-speech watchdog, utterance floor, and request timeout all have hard limits.
• A press supersedes the previous session and discards its buffer, so a stale transcript can never land in the new target.

Related documentation

• settings-trust.md — settings.json and the live key
• cli-modes.md — /live in the slash-command surface

Models and custom providers

Built-in catalog

rpi ships with an embedded model catalog in crates/pi-ai/src/models_catalog.json. The catalog is loaded once on first use and restored for built-in provider ids when a custom models.json is reloaded.

List available models with:

rpi models
rpi models claude

The filter is case-sensitive and matches provider name or model id. The list also reflects model entitlements from the resolved credential (e.g., GitHub Copilot OAuth model lists).

Supported API identifiers

A model's api field selects the wire protocol. The identifiers registered by the built-in provider set are (source: crates/pi-ai/src/types.rs / crates/pi-ai/src/providers/mod.rs):

Model spec resolution

When you write rpi -m <spec> or use /model in the REPL, rpi resolves it with the following algorithm (source: crates/pi-coding/src/resolve.rs):

1. If the text before the first / matches a known provider id (exactly, case-insensitively), the rest is treated as the model id within that provider: anthropic/claude-sonnet-4-5.
2. Otherwise the whole string is matched as a bare model id across all providers. This allows OpenRouter-style ids that contain their own slashes, e.g. openrouter/ai21/jamba-large-1.7.
3. Case-insensitive substring matching on model id and name. Aliases (ids ending in -latest or without a -YYYYMMDD date suffix) are preferred over dated versions; otherwise the latest dated version by descending id is used.
4. If the provider is known but the id is not, rpi synthesizes a custom-id model by cloning that provider's default template (defaultModelPerProvider), or the provider's first model if no default is defined. A warning is emitted.

A thinking-level suffix :off|minimal|low|medium|high|xhigh is parsed off the end of the spec. On a custom-id fallback the suffix is stripped from the id first. The CLI --thinking flag accepts off|minimal|low|medium|high|xhigh|max (max is an alias for xhigh). If the resolved model does not have reasoning: true, only off is available; a non-off suffix on a custom fallback enables reasoning: true for that request.

When no spec is given, the default is anthropic/claude-sonnet-4-5.

Examples:

rpi -m anthropic/claude-sonnet-4-5
rpi -m claude-sonnet-4-5:high
rpi -m openrouter/ai21/jamba-large-1.7
rpi -m my-provider/my-custom-model:low
rpi -m llama.cpp/llama-3.1-8b

Custom providers via models.json

Place models.json in the agent directory ($PI_CODING_AGENT_DIR, or the default agent directory under your home). If no explicit agent directory or home directory is available, custom configuration is disabled and the current working directory is never used as a fallback.

OpenAI-compatible proxy

{
  "providers": {
    "cliproxy": {
      "baseUrl": "https://api.example.com/v1",
      "api": "openai-completions",
      "models": [
        { "id": "gpt-5.5", "maxTokens": 8192 }
      ]
    }
  }
}

Cloudflare AI Gateway

{
  "providers": {
    "cf-gateway": {
      "baseUrl": "https://gateway.ai.cloudflare.com/v1/{CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}/openai/",
      "api": "openai-completions",
      "apiKey": "$CLOUDFLARE_API_KEY",
      "models": [
        { "id": "@cf/moonshotai/kimi-k2.6" }
      ]
    }
  }
}

The placeholders {CLOUDFLARE_ACCOUNT_ID} and {CLOUDFLARE_GATEWAY_ID} are substituted from the environment at request time. See environment-variables.md.

Anthropic with a bearer token

{
  "providers": {
    "anthropic": {
      "apiKey": "$ANTHROPIC_AUTH_TOKEN",
      "authHeader": true,
      "models": []
    }
  }
}

A provider-level override with an empty models array keeps the built-in Anthropic models unchanged but applies the provider-level apiKey, authHeader, baseUrl, headers, or compat.

Override a built-in model

{
  "providers": {
    "openai": {
      "models": [
        { "id": "gpt-5.5", "maxTokens": 16384 }
      ]
    }
  }
}

The per-model entry is merged with the built-in entry; maxTokens and other fields override defaults.

models.json schema

Top level:

{
  "providers": {
    "<provider-id>": {
      "name": "Display name",
      "baseUrl": "https://...",
      "api": "openai-completions",
      "apiKey": "$VAR",
      "authHeader": false,
      "headers": { "x-foo": "$FOO" },
      "compat": { "supportsStrictMode": true },
      "models": [
        {
          "id": "model-id",
          "name": "Display name",
          "api": "openai-completions",
          "baseUrl": "...",
          "reasoning": true,
          "thinkingLevelMap": { "off": null, "high": "high" },
          "input": ["text", "image"],
          "cost": { "input": 3.0, "output": 15.0, "cacheRead": 1.5, "cacheWrite": 0.5 },
          "contextWindow": 200000,
          "maxTokens": 8192,
          "headers": { "x-model": "value" },
          "compat": { "supportsReasoningEffort": false }
        }
      ]
    }
  }
}

Rules:

• A provider must define at least one of baseUrl, headers, compat, apiKey, authHeader, or models.
• api and baseUrl can be set at provider level and overridden per model. Custom models require an api and a baseUrl somewhere in the fallback chain; otherwise loading fails closed.
• Model-level fields override provider-level fields.
• reasoning: true enables the off|minimal|low|medium|high|xhigh level ladder; without it only off is available.
• thinkingLevelMap can disable a level ({ "xhigh": null }) or map a level name to a provider-specific value.
• compat is merged. Nested openRouterRouting, vercelGatewayRouting, and chatTemplateKwargs objects are merged deeply; all other compat keys are replaced.
• For custom model entries, defaults are: input ["text"], contextWindow 128000, maxTokens 16384, empty cost, no compat.

The llama.cpp provider

When a llama.cpp router is configured (rpi llama configure URL or LLAMA_BASE_URL), live router models are merged into the catalog under the provider id llama.cpp. Select them with:

rpi -m llama.cpp/llama-3.1-8b

At startup rpi refreshes the live router catalog unless PI_OFFLINE=1|true|yes is set. If the router is unavailable, rpi falls back to the cached catalog stored in the agent directory. Router configuration and the cache are written atomically; the settings file must not be readable by group or other users on Unix. See local-llama.md for router setup and GGUF downloads.

GitHub Copilot

github-copilot is treated specially:

• It uses COPILOT_GITHUB_TOKEN for bearer authentication.
• Before each request it adds dynamic headers based on the context:
  • X-Initiator: user when the last message is from the user, otherwise agent.
  • Openai-Intent: conversation-edits.
  • Copilot-Vision-Request: true when the context contains image content.
• Models are filtered by the entitlements returned for the resolved credential.

Capability flags in compat

Common flags used by the built-in providers:

The full set of flags and defaults is defined in the provider source files (crates/pi-ai/src/providers/*.rs).

Authentication

rpi resolves credentials in a strict, documented order and never logs them. Credentials can be managed interactively with rpi login / rpi logout or configured manually in auth.json or models.json.

Quick credential management

# Interactive login (choose provider and method)
rpi login

# Login to a specific provider
rpi login anthropic

# Remove stored credentials
rpi logout openai

login and logout operate on the agent's auth.json. Outside an interactive terminal they require an explicit provider argument. auth.json is written atomically with 0o600 file permissions and 0o700 directory permissions on Unix.

Credential precedence (per provider)

When a request is built, rpi looks for a usable credential in this order (source: crates/pi-cli/src/models_config.rs::resolve_model_request_auth and resolve_model_request_auth_async):

1. An explicit API key passed at call time, e.g. --api-key on the CLI (--api-key requires --model or --models).
2. A runtime key set for the provider (the CLI stores --api-key as a runtime key for the resolved provider for the duration of the run).
3. A stored auth.json credential for the provider:
   • api_key entries are expanded and used as the key.
   • OAuth entries require async resolution; rpi refreshes expired OAuth tokens automatically before use.
4. The apiKey field from models.json for that provider.
5. A recognized provider environment variable (see table below).
6. Anthropic-specific bearer handling: when the API-key slot is still empty, ANTHROPIC_AUTH_TOKEN is sent as Authorization: Bearer <token> and is never treated as an x-api-key value.
7. Provider-specific header-only auth configured in models.json or model headers, e.g. authorization, x-goog-api-key, or cf-aig-authorization.

If none of the above produce a key or recognized auth header, the request fails closed with an error naming the provider.

All header-name lookups are case-insensitive. Header and credential values support $VAR / ${VAR} template expansion (see Template expansion).

Supported OAuth providers

rpi login can store OAuth credentials for:

• anthropic
• openai-codex
• google-gemini-cli
• xai
• openrouter
• kimi-coding

Other providers default to API-key authentication. OAuth tokens are refreshed automatically when expired (with a 5-minute skew). OAuth credentials may carry model entitlements (available_model_ids); models outside those entitlements are hidden for that credential.

Environment variables by provider

Provider-specific notes:

• Anthropic: ANTHROPIC_OAUTH_TOKEN wins over ANTHROPIC_API_KEY when an API key is requested. ANTHROPIC_AUTH_TOKEN is used as a bearer token in the Authorization header only when the API-key slot is empty, and is never used as an x-api-key value.
• GitHub Copilot: COPILOT_GITHUB_TOKEN is required. The provider adds dynamic per-request headers (X-Initiator, Openai-Intent, and Copilot-Vision-Request when images are present).
• Amazon Bedrock: ambient AWS credentials are intentionally not read. When one of the listed AWS credential sources is present, the resolved key is the sentinel <authenticated> and the AWS SDK signs the request.
• Google Vertex: GOOGLE_CLOUD_API_KEY supplies an API key, or GOOGLE_CLOUD_ACCESS_TOKEN / an authorization header can supply an access token. The provider never reads Application Default Credential files or credential helpers. Vertex requests also require GOOGLE_CLOUD_PROJECT (alias GCLOUD_PROJECT) and GOOGLE_CLOUD_LOCATION.

auth.json

auth.json lives next to models.json in the agent directory ($PI_CODING_AGENT_DIR, or the default agent directory under your home). Example:

{
  "openai": {
    "type": "api_key",
    "key": "$OPENAI_API_KEY",
    "env": {
      "OPENAI_API_KEY": "<your-openai-key>"
    }
  }
}

Rules:

• type is "api_key" for manually edited entries. rpi login may write "oauth" entries; those should not be hand-edited.
• key is the credential value or a $VAR / ${VAR} template.
• env is an optional map of variables available only while resolving this credential.
• $$ becomes a literal $; $! becomes a literal !.
• Command-valued keys ("key": "!some-command") are rejected.

models.json authentication

Custom and overridden providers in models.json can carry authentication independently of auth.json:

{
  "providers": {
    "my-proxy": {
      "baseUrl": "https://api.example.com/v1",
      "api": "openai-completions",
      "apiKey": "$MY_PROXY_KEY",
      "authHeader": true,
      "headers": {
        "x-custom": "$CUSTOM_HEADER"
      },
      "models": [
        {
          "id": "my-model",
          "maxTokens": 4096
        }
      ]
    }
  }
}

Rules:

• authHeader: true sends Authorization: Bearer <apiKey>. It requires a resolved API key; if none exists the request fails closed.
• Provider-level headers apply to every model of that provider; per-model headers override them. Merging is case-insensitive last-wins.
• apiKey, baseUrl, and header values support $VAR / ${VAR} expansion from the process environment. models.json does not support a per-entry env map (only auth.json credentials do). $$ is a literal $ and $! is a literal !. Unset variables produce an error.
• Command-valued apiKey or header values ("!command") are rejected.

Template expansion

Both auth.json and models.json values use the same expander (source: crates/pi-coding/src/auth.rs::expand_credential_value and crates/pi-cli/src/models_config.rs::resolve_config_value_with_fallback):

For auth.json, variables are resolved from the request environment, then the credential's own env map, then the process environment. Empty values are treated as unset. Invalid braced names such as ${1bad} are left unchanged. If a referenced variable is not set, rpi exits with an error that names the variable and source file but never exposes the original template text.

Redaction and sensitive headers

The following headers are treated as sensitive and are marked with set_sensitive(true) so they are hidden from request traces and logs:

• authorization
• x-api-key
• cf-aig-authorization
• x-goog-api-key

When an error message is produced by pi_messages, radius, mistral, or similar providers, the raw API key and any bearer-token values found in the above headers are stripped from the message before it is surfaced. Error messages name the missing variable or provider, never the key value.

Fail-closed behavior

rpi fails loudly rather than silently when authentication cannot be resolved:

• No API key, no OAuth credential, no recognized auth header, and no authHeader fallback → request fails with: no API key found for provider ....
• authHeader: true without a resolved API key → request fails.
• A $VAR reference in auth.json or models.json resolves to an unset variable → request fails.
• Azure OpenAI requests with zero or more than one of authorization / api-key → request fails.
• Google Vertex requests with both authorization and x-goog-api-key in the same scope → request fails.
• Amazon Bedrock requests with only one of AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY → request fails.

Do not commit auth.json or models.json containing real keys.

RPC JSONL protocol

rpi --mode rpc and the rpi rpc subcommand expose a long-lived, LF-delimited JSONL control protocol on stdin/stdout. The protocol is not JSON-RPC 2.0: every line is a single self-describing JSON object with a type discriminator, and every command can carry an optional id that the matching response echoes.

Launching the RPC mode

• rpi --mode rpc [<other rpi flags>] starts the RPC server on stdin/stdout.
• rpi rpc [<other rpi flags>] is equivalent: the subcommand forces --mode rpc, so the server always enters RPC mode. A conflicting explicit --mode is rejected. On fatal initialization error the server writes a failure response line to stdout.

Both forms are headless and never prompt for project trust; pass --approve when you need project-local .pi resources.

Framing

• Every record is exactly one JSON object followed by a single line feed (\n, byte 0x0A). There is no batching, length prefix, or JSON-RPC envelope.
• The writer serializes each record with serde_json::to_writer, appends \n, and flushes, so clients can read line-by-line.
• The reader splits incoming bytes on \n. A trailing carriage return (\r) is stripped before parsing, so \r\n sources are tolerated.
• If stdin reaches EOF while the last partial line is non-empty, that partial line is delivered as the final frame.

Request envelope

Every command line is a JSON object containing at minimum:

{"type": "<command>", "id": "optional-correlation-id", ...}

• type — required string, snake-cased command name (see the table below).
• id — optional string. If present it is echoed in the matching response. Commands that do not need correlation may omit it.

Response envelope

A response line has the fixed shape:

{
  "id": "optional-correlation-id",
  "type": "response",
  "command": "<command>",
  "success": true,
  "data": { ... }
}

On failure:

{
  "id": "optional-correlation-id",
  "type": "response",
  "command": "<command>",
  "success": false,
  "error": "human-readable message"
}

• id matches the request id when one was provided; otherwise it is omitted.
• command repeats the request's type value.
• data is present on success and is null for commands that return no payload.
• error is present on failure.

Correlation and asynchronous events

Command/response pairs correlate by id. In addition to responses, the host emits asynchronous ApplicationEvent records on the same stdout stream. Events have their own type tag (e.g. session_started, agent_start, agent_settled, todo_updated, process_started) and no id. A client should therefore read all stdout lines, dispatch "response" records by id, and dispatch events by type.

A minimal exchange looks like:

{"type":"session_started","data":{"version":3,"id":"...","timestamp":"...","cwd":"<workspace>"}}
{"type":"prompt","id":"1","message":"List Rust files"}
{"id":"1","type":"response","command":"prompt","success":true,"data":null}
{"type":"agent_settled"}

Malformed input and recovery

The RPC loop never aborts because of a bad line; it emits a failure response and continues reading.

• Invalid JSON → {"type":"response","command":"parse","success":false,"error":"Failed to parse command: ..."}. Because serde_json::from_slice fails before the object is inspected, an invalid JSON line cannot preserve an id.
• Missing type field → failure response with the preserved id.
• Unknown type value → {"id":"...","type":"response","command":"<type>","success":false,"error":"Unknown command: <type>"}.
• Invalid fields for a known command → failure response with command set to the command name and id preserved.
• Invalid extension_ui_response → failure response with "command": "extension_ui_response".

Because lines are split before parsing, a malformed line never corrupts the following valid lines.

Extension UI requests and responses

When an extension asks to show UI, the host emits an extension_ui_request record with a unique id and a flattened method object:

{
  "type": "extension_ui_request",
  "id": "ui-1",
  "method": "confirm",
  "title": "Approve destructive edit?",
  "message": "This will overwrite src/main.rs"
}

Supported methods include select, confirm, input, editor, notify, setStatus, setWidget, setTitle, and set_editor_text. The client replies with an extension_ui_response carrying the same id and one of:

{"type":"extension_ui_response","id":"ui-1","confirmed":true}
{"type":"extension_ui_response","id":"ui-1","value":"typed answer"}
{"type":"extension_ui_response","id":"ui-1","cancelled":true}

Notification/status/widget requests are generated with a host-assigned id and are one-way; the client does not need to reply to them.

Stdout isolation

All protocol output goes through a single mutex-protected stdout writer; every record is produced by the same JSONL write path. No ordinary command handler, event path, or tool prints raw text to stdout. Runtime diagnostics and panics are routed to stderr, so stdout remains exclusively JSONL protocol records.

Command reference

The following table lists every current RpcCommand variant exactly once. All commands accept an optional id. Required fields are shown without brackets; optional fields are shown with [...] and their JSON key.

Common payload notes

• images items are ContentBlock objects; an inline image looks like {"type":"image","data":"<base64>","mimeType":"image/png"}.
• QueueMode values serialize as kebab-case: "all" and "one-at-a-time".
• ThinkingLevel values are lowercase: "off", "minimal", "low", "medium", "high", "xhigh".
• ProcessSignal values serialize as SCREAMING_SNAKE_CASE.
• ProcessKey values serialize as the variant names shown above.
• ProcessId is a string (UUID v7 in generated ids), not a number.

Example RPC session

{"type":"prompt","id":"1","message":"List Rust files"}
{"type":"get_state","id":"2"}
{"id":"1","type":"response","command":"prompt","success":true,"data":null}
{"id":"2","type":"response","command":"get_state","success":true,"data":{"thinkingLevel":"medium","isStreaming":false,"sessionName":"demo"}}
{"type":"agent_settled"}
{"type":"bash","id":"3","command":"ls *.rs"}
{"id":"3","type":"response","command":"bash","success":true,"data":{"exitCode":0,"stdout":"main.rs\nlib.rs\n"}}

For a complete Rust client example, see examples/src/bin/rpc_client.rs.

Web client (/web)

rpi --listen serves a web chat client at GET /web on the control-plane listener. The frontend is a React + TypeScript app (crates/pi-cli/web/, built with Vite); vite-plugin-singlefile inlines it into one self-contained dist/index.html that build.rs embeds into the binary as an asset table (path -> MIME/bytes). At runtime there is no framework, build step, or external asset — the listener serves the embedded page, and the page drives the existing WebSocket control plane in a browser.

Frontend development uses the Vite dev server:

$ rpi --listen 127.0.0.1:8765 --listen-token-file <workspace>/rpi-token
$ cd crates/pi-cli/web
$ npm install
$ RPI_LISTEN=http://127.0.0.1:8765 npm run dev   # http://localhost:5173

The dev server proxies /ws and /rpc to the listener. npm run build regenerates the committed dist/index.html; rebuilding the Rust binary embeds the new bundle. RPI_WEB_DEV_DIR=<dir> makes the listener serve a built page from disk instead, for iterating without recompiling Rust.

Starting the listener

rpi --listen is a headless Web-only backend. It never initializes terminal raw mode, cursor probing, a TUI, or a line REPL. Standard input may be closed; the service stays alive until Ctrl-C or SIGTERM, then flushes the active session and shuts down its listener and runtime manager cleanly. Web prompts use the normal session recorder, so restarting with --continue, --resume, --session, or --session-id restores the recorded conversation.

Authentication is optional: a tokenless listener accepts browser connections directly, and a configured token makes authentication mandatory.

One-command local startup (loopback, no token — the browser auto-connects):

$ rpi --listen 127.0.0.1:8765
Control plane listening on http://127.0.0.1:8765 (loopback only)

Open http://127.0.0.1:8765/web in a browser; the page auto-connects with no token and is ready to use. This is the default for local single-user work.

Tokenless LAN access — bind a non-loopback address and opt into plaintext remote listening (still no token):

$ rpi --listen 0.0.0.0:8765 --listen-allow-insecure-remote

Open http://<host-lan-ip>:8765/web — or any hostname that routes to the host — from another machine on the LAN; the page auto-connects with no token. No --listen-advertised-origin is needed for ordinary /web, /ws, or /rpc: the browser request is accepted when its Origin authority equals the HTTP Host — an ordinary same-origin check that rejects unrelated cross-origin pages, not authentication and not DNS-rebinding protection. This is plaintext HTTP and WebSocket with no authentication and no encryption: anyone reachable on the network can drive the agent and observe traffic. Use loopback, or a TLS-terminating proxy in front of the listener, unless that exposure is explicitly acceptable.

Optional authenticated form — add --listen-token-file to make the token mandatory on either bind:

$ rpi --listen 127.0.0.1:8765 --listen-token-file <workspace>/rpi-token
Control plane listening on http://127.0.0.1:8765 (loopback, authentication enabled)

Open http://127.0.0.1:8765/web, enter the token, and press Connect. For an authenticated LAN listener, combine the token file with the insecure-remote opt-in:

$ rpi --listen 0.0.0.0:8765 --listen-token-file <workspace>/rpi-token \
      --listen-allow-insecure-remote

The token authenticates clients but provides no encryption: passive LAN observers can still capture the bearer token and control traffic.

Collaboration join links follow the same bind/advertise separation: wildcard binds (0.0.0.0 or ::) require --listen-advertised-origin <URL> (a strict http/https origin without credentials, path, query, or fragment) before /collab — or collab_start without an explicit baseUrl — can print reachable links; loopback binds advertise their local address automatically.

The page itself is always served without authentication: it carries no data, and every command and event flows through the /rpc and /ws routes, which are token-gated only when a token file is configured.

Authentication: the rpi-auth.<token> subprotocol

Browsers cannot set the Authorization header on WebSocket connections. The listener therefore accepts the token as a WebSocket subprotocol request:

Sec-WebSocket-Protocol: rpi-auth.<token>

• The offered list is scanned for the first rpi-auth.<token> entry whose token matches the configured token file, compared in constant time (the same comparison used for Authorization: Bearer <token>).
• On success the exact offered protocol is reflected in the upgrade response (RFC 6455 requires the server to select and echo one subprotocol), so the browser accepts the handshake.
• The Authorization header path is unchanged. A token file makes the token mandatory on every bind; without one the listener is tokenless — browsers are accepted on loopback, and on a non-loopback bind with --listen-allow-insecure-remote when the request's Origin authority equals the HTTP Host (an ordinary same-origin check that rejects unrelated cross-origin pages, not authentication and not DNS-rebinding protection). Wrong, empty, or whitespace-containing candidates are rejected. A configured token authenticates clients but provides no encryption against passive network observers.

The token never appears in a URL or cookie; it is held only in the WebSocket handshake header and kept in sessionStorage by the page.

v1 features

• Connection state + auto-reconnect — the status pill shows connecting / connected / reconnecting / offline; unexpected disconnects retry with exponential backoff (1s → 15s cap). A manual Connect button reconnects after changing the token.
• Prompt box — while idle, Enter and the primary Send button send prompt; while a run is active, both switch to Steer and send steer, avoiding a rejected second prompt. Shift+Enter inserts a newline; Esc (or the active-only Abort button) stops the run. Redundant dedicated Steer and Follow up buttons are intentionally absent, leaving the textarea usable on phone-width screens.
• Streaming transcript — assistant turns render live from the event stream: text deltas, collapsible thinking blocks, compact tool-call cards, bash/tool-result blocks, and final markdown. Internal display: false system scaffolding is hidden like the TUI; bash output keeps the last 10 lines and other tool output keeps the last 6 with an omitted-line count.
• Model / thinking switch — model and thinking-level dropdowns populated from get_available_models / get_available_thinking_levels, applying set_model and set_thinking_level; the session name comes from get_state.
• Status line — a pulsing "streaming" badge while a run is in flight and error toasts for failed commands, failed runs, and connection problems.
• Multi-session authoritative restore — switching sessions consumes the target runtime's backend snapshot; closed sessions resume from disk, and a listener restart rebinds before controls become active. Web prompts use the normal session recorder and remain available after restart.
• Panels — dedicated views for todo, goal, workflow, session tree, settings, subagent jobs, side chat, and maintenance, each driven by the same JSONL RPC control plane.
• Collaboration guest route — /collab/ws/<roomId> serves the same embedded client for encrypted live-collaboration guests, reading the capability key from the URL fragment locally before opening the encrypted WebSocket.

Security

• Every model-derived string passes through a JavaScript port of the export pipeline's redact_secrets (credential shapes such as sk-…, ghp_…, Bearer …, token=…, PEM private keys) before touching the DOM, and every string crossing into innerHTML is additionally HTML-escaped (& < > " '). Streaming deltas use textContent; model text is never injected as raw HTML.
• Links are restricted to http/https/mailto and same-origin relative paths; images only render from base64 data: URIs with whitelisted MIME types.
• The token is never placed in a URL, and there is no cookie, so nothing to CSRF. Commands require the token only when one is configured; the page itself is static.

v1 limitations

• Remote approvals and overlay confirmations are intentionally unavailable (extension_ui_response is hard-rejected on the wire by design); the page shows tool results but cannot answer interactive extension prompts.
• No TLS: the listener is plain HTTP/WebSocket. Non-loopback access is an explicit plaintext opt-in (optionally authenticated), and passive network observers can capture any bearer token and control traffic.

Testing

• Frontend type-check + build: cd crates/pi-cli/web && npm run build (type-check, focused transcript assertions, Vite bundle, and deterministic trim); the committed dist/index.html is what the binary embeds.
• Rust: cargo test -p pi-cli --lib (subprotocol unit tests) and cargo test -p pi-cli --test listen_control_plane (GET /web route, positive and negative subprotocol auth, existing routes unchanged).
• Browser E2E (playwright-only hard gate): bash E2E.d/web/run.sh spawns the real binary with the loopback mock provider and runs 12 lanes: core, goal, xss, abort, reconnect, switch, mobile, auth, auth_tokenless, extras, sessions, and session_restore. The final lane proves loaded switching, close/resume from disk, and listener-restart history restoration. Most lanes use a token file; auth_tokenless starts without one. Playwright uses a system Chrome/Chromium binary or its bundled Chromium; an unavailable browser or failed assertion fails the lane with no skip or fallback.

E2E scenarios (user-perspective tmux tests)

This page is the scenario catalog for user-perspective, goal-driven E2E testing of the rpi TUI. Every entry is written the way a user would experience the product: a user goal, the concrete tmux interaction that pursues it, the observable outcome on the real TUI, and the pass criteria that prove the goal was achieved. The catalog covers every core feature; the highest-value scenarios are implemented as runnable, deterministic tmux scripts under E2E.d/ (see Implementation status).

How scenarios are executed

• The binary under test is target/release-dist/rpi (RPI_BIN).
• Scenarios that need no model tool calls use the built-in faux provider (--model faux/faux-1 + PI_FAUX_RESPONSE): fully offline and deterministic.
• Scenarios that must exercise tool calls (bash cards, todo DAG creation, workflow planning/workers) use a loopback mock provider (an OpenAI-compatible SSE server on localhost), never a real model — still offline and deterministic.
• Every script: starts tmux → launches rpi with the scenario's flags/model → drives keystrokes → asserts on pane text (status line, panel rows, output) and/or file side effects → captures evidence under EVIDENCE_ROOT → kills the session.
• Scripts are self-contained, skip-guarded (tmux present, RPI_BIN executable, faux model available), and use bounded wait-for-pattern polling instead of sleeps wherever possible.
• Run a single scenario or the whole lane:

# whole lane
bash E2E.d/ci/user_scenarios.sh run
# one scenario
bash E2E.d/ci/user_scenarios.sh goal
# list
bash E2E.d/ci/user_scenarios.sh list

Evidence lands in ${TMPDIR:-/tmp}/rpi-e2e-evidence/<run-id>/user-<scenario>/.

Scenario catalog

Legend — script: implemented in this repo and runnable now; lane: covered by an existing E2E lane (E2E.d/ci/*.sh or Rust tests/); manual: needs hardware/credentials/network, runs by hand only.

1. Goal lifecycle (create / pin / pause / complete + budget + journal)

2. Loop (create / cancel / delete / continue)

3. Workflow (plan → todo → execute → integrate; isolation; restart)

4. Orchestration (subagents spawn/delegate, IRC, soft budgets, yield)

5. Todo DAG (list / detail / execute)

6. /btw side chat

7. /live voice (hold-to-talk)

8. MCP (stdio server connect + tool call)

9. ACP (agent stdio session)

10. Extensions (overlay open, plugin install from dir/git, trust)

11. /rewind + /snapcompact + /compact

12. /handoff

13. /fresh, /dump, /share --encrypt

14. Hooks / trust

15. Sandbox (bash denied path)

16. Image generation (faux)

17. Eval / notebook (python cell)

18. Memory tool

19. Ask tool

20. Auto-mode

21. /queue + doom-loop

22. TUI chrome (theme, status line, bash cards, code frames, list colors, steering queue)

Implementation status

All other features are covered by the lanes listed in the catalog; /live voice and real image generation are manual.

Verification

First full green run (2026-08-08): bash E2E.d/ci/user_scenarios.sh run → exit 0. Re-verified on the post-web-wave tree (2026-08-09, freshly rebuilt target/release-dist/rpi, rust-toolchain 1.88.0): bash E2E.d/ci/user_scenarios.sh run → exit 0.

Notes from verification:

• Scenario scripts must run against a current release-dist binary; the previously shipped one (Aug 5) predated /goal pin and reported a current goal already exists on pin.
• The status text set by a command that starts a model turn (Goal work started …) is immediately superseded by the turn's busy label, so the scripts assert the details block, the header chip, and the post-turn statuses instead.
• /snapcompact's Compacted A → B estimated tokens status can be overwritten by the session's Compaction complete event (event ordering); the scripts accept either and assert the sidecar archive durably.
• The non-snap /compact LLM summarizer requires > keepRecentTokens of context before it has anything to compact, which a short faux session cannot reach; that surface stays covered by unit tests and the Rust REPL lanes.
• The workflow supervisor prompt reads You plan workflow …; loopback mocks must classify on that wording, and multi-tool-call responses must stream one tool_calls index per SSE delta.

Settings, configuration, and trust

Configuration directory

The runtime resolves the agent configuration directory (<agent-dir>) in this order:

1. PI_CODING_AGENT_DIR environment variable.
2. The platform home directory (HOME on Unix, USERPROFILE on Windows) with /.pi/agent appended.

Source: crates/pi-coding/src/resources.rs:26-41.

Within <agent-dir> the CLI reads:

• settings.json — global startup defaults and operational settings.
• models.json — custom providers and model overrides.
• auth.json — stored provider credentials.
• trust.json — persisted project trust decisions.
• sessions/ — native Pi v3 JSONL session files.
• skills/, prompts/, themes/ — global resources.

Project-local resources are loaded from <workspace>/.pi/ only when that project is trusted. Source: crates/pi-coding/src/resource_manager.rs:49-70.

Project trust

By default, rpi asks before loading project-local .pi resources (skills, prompts, themes, keybindings, extensions, agents, and package settings). Trust decisions are stored in <agent-dir>/trust.json, versioned as TRUST_STORE_VERSION = 1, and scoped to the canonical project path. The resolver walks parent directories, so a decision at <workspace> covers <workspace>/sub-project.

Source: crates/pi-coding/src/trust.rs:67-140 and crates/pi-coding/src/trust.rs:180-216.

Default behavior is controlled by settings.json:

{
  "defaultProjectTrust": "ask"
}

Allowed values:

• "ask" — prompt for trust in interactive modes; treat as untrusted in headless modes (default).
• "always" — trust every project with a .pi directory without asking.
• "never" — never trust project-local resources.

One-run overrides:

rpi -a "hello"           # --approve: trust this project's .pi for this run
rpi --no-approve "hello" # refuse project .pi for this run

Headless modes (--print, --mode json, --mode rpc) never prompt. In headless mode an unset or "ask" decision is treated as untrusted, so use --approve when you need project resources. If the project has no .pi directory, it is implicitly trusted.

Source: crates/pi-coding/src/trust.rs:37-43 and crates/pi-cli/src/args.rs:168-174.

settings.json

Global settings live at <agent-dir>/settings.json. Project settings live at <workspace>/.pi/settings.json and are merged on top of global settings when trusted. Unknown fields are retained across merges so other product modules can use them.

Source: crates/pi-coding/src/settings.rs:666-669 and crates/pi-coding/src/settings.rs:729-843.

{
  "defaultProvider": "openai",
  "defaultModel": "openai/gpt-5",
  "defaultThinkingLevel": "medium",
  "defaultProjectTrust": "ask",
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "reserveTokens": 8192,
    "keepRecentTokens": 4096
  },
  "terminal": {
    "showImages": true,
    "imageWidthCells": 80,
    "clearOnShrink": false,
    "showTerminalProgress": true
  },
  "images": {
    "autoResize": true,
    "blockImages": false
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 2000,
    "provider": {
      "timeoutMs": 60000,
      "maxRetries": 3,
      "maxRetryDelayMs": 60000
    }
  },
  "transport": "auto",
  "timeoutMs": 60000,
  "maxRetryDelayMs": 60000,
  "temperature": 0.7,
  "maxTokens": 4096,
  "cacheRetention": "short",
  "thinkingBudgets": {
    "minimal": 1024,
    "low": 2048,
    "medium": 4096,
    "high": 8192
  },
  "scopedModels": ["openai/*", "anthropic/*"],
  "branchSummary": {
    "reserveTokens": 16384,
    "skipPrompt": false
  },
  "keybindings": {
    "toggleTheme": "ctrl+t"
  },
  "quietStartup": false,
  "showThinking": true,
  "exposeSessionEnvironment": true,
  "doubleEscapeAction": "tree",
  "orchestration": {
    "process": false,
    "tasks": false,
    "todo": false,
    "maxConcurrency": 8,
    "maxRecursionDepth": 8,
    "mailboxCapacity": 1000,
    "maxToolsPerAgent": 16
  },
  "packages": [
    "git:github.com/owner/pi-my-tools",
    { "source": "./my-pi-tools", "extensions": ["*"] }
  ],
  "extensions": ["ext-id"],
  "skills": ["rust-review"],
  "prompts": ["custom-prompt"],
  "themes": ["solarized"]
}

Known fields

Source: crates/pi-coding/src/settings.rs:342-416, crates/pi-coding/src/settings.rs:970-1096, and crates/pi-coding/src/settings.rs:1104-1129.

Supported operational settings coverage

The following keys are the supported operational settings coverage used by the runtime. Any other field may exist but is either a startup default, a resource list, or module-specific configuration.

Source: crates/pi-coding/src/settings.rs:302-330.

Model and thinking-level precedence

When the CLI starts without an explicit model:

1. --model / -m flag.
2. Resumed session's saved model (when --resume or --continue is used).
3. settings.json defaultModel.
4. First authenticated model in the catalog.

Thinking level precedence:

1. --think flag.
2. Thinking level parsed from a :level model suffix (anthropic/claude-sonnet-4-5:high).
3. Resumed session's saved thinking level.
4. settings.json defaultThinkingLevel.
5. medium.

The final level is clamped to the resolved model's supported levels.

Live reload semantics

Configuration and resources are loaded into an atomic snapshot.

• rpi reload validates the current settings/resource graph and prints a structured snapshot, including generation, trust, discovered resources, and diagnostics. It always runs headlessly and emits JSON.
• SettingsManager::reload() re-reads global settings and, when the project is trusted, project settings, then recomputes the effective snapshot.
• ResourceManager::stage_reload() builds a new candidate snapshot without replacing the active one. commit_reload() swaps the active snapshot only after validation succeeds; any error leaves the previous generation in place.
• Interactive TUI /reload and REPL reload call the same stage-and-commit path, so malformed files never silently replace a working configuration.
• Settings writes performed through update_global or update_project are atomic (temp file + fs::rename + directory sync). Session-only overrides via apply_overrides are never persisted.

Source: crates/pi-cli/src/commands.rs:145-180, crates/pi-coding/src/settings.rs:729-843, and crates/pi-coding/src/resource_manager.rs:139-253.

Trust boundaries

• No project-local configuration is loaded unless the project is trusted. Use -a/--approve or set defaultProjectTrust explicitly.
• approvalMode is a global safety policy and is rejected in project .pi/settings.json; --approval-mode is the explicit one-run override. It is independent of --approve/--no-approve, which control only project resource trust.
• Interactive approval runs before the existing host hook and extension reducer. Headless modes fail closed whenever the selected policy requires confirmation.
• Bash tool commands run in the configured working directory (--cwd).
• API keys are never printed in error messages or logs.
• models.json and auth.json values may contain $VAR / ${VAR} templates, which are expanded from the current process environment or an explicit env map. Command-valued values (!command) are rejected.

Custom config path for tests or isolation

export PI_CODING_AGENT_DIR="<workspace>/.my-pi-config"
mkdir -p "$PI_CODING_AGENT_DIR"
rpi --print "hello"

pi-coding 架构图（Mermaid）

来源：对 crates/pi-coding（约 128K 行 Rust）的结构分析。所有引用以 <repo-root>/crates/... 相对路径 + 行号给出，可执行验证：grep -n "<symbol>" crates/pi-coding/src/<file>.rs。

图 0 — 四层 crate 依赖

flowchart TB
    subgraph L0["pi-cli — crates/pi-cli"]
        TUI["TUI 面板 / REPL<br/>tui.rs · repl.rs"]
        RPC["JSON-RPC / ACP 模式<br/>rpc.rs · acp.rs"]
        CMD["子命令 · 会话编排<br/>interactive_commands.rs · session_run.rs"]
    end
    subgraph L1["pi-coding — crates/pi-coding（本图主体）"]
        APP["Application 状态机<br/>application.rs"]
        SESS["Session 回合执行<br/>session.rs"]
        SUB["工具 · 编排 · 工作流<br/>扩展 · 配置 · 持久化"]
    end
    subgraph L2["pi-agent — crates/pi-agent"]
        AGENT["Agent 循环<br/>agent.rs · loop_runtime.rs"]
    end
    subgraph L3["pi-ai — crates/pi-ai"]
        PROV["providers/<br/>anthropic · openai · responses · codex · gemini..."]
        CAT["模型目录 · 流式 · 重试 · 超时<br/>catalog.rs · stream.rs"]
    end
    TUI --> APP
    RPC --> APP
    CMD --> APP
    APP --> SESS
    SESS --> AGENT
    AGENT --> PROV
    PROV --> CAT
    classDef lay fill:#eef7ff,stroke:#1565c0
    class L0,L1,L2,L3 lay

依赖方向（AGENTS.md 约束）：pi-cli → pi-coding → pi-agent → pi-ai，禁止跨层直取内部实现。

图 1 — pi-coding 内部模块全景

flowchart LR
    subgraph CORE["回合核心"]
        APP1["Application 状态机<br/>application.rs:335<br/>+ application/runtime.rs"]
        SESS1["Session<br/>session.rs:717<br/>turn loop · retry · compaction"]
        STORE["session_store.rs<br/>SessionRecorder:607 · start_session:1177<br/>resume:1551 · fork:1473"]
    end
    subgraph TOOLS["工具子系统 tools.rs + tools/*"]
        CAT["工具目录<br/>tools.rs:537 create_all_tools"]
        BASH["bash/brush · process/<br/>ProcessManager:23"]
        EDIT["edit · write · ast_edit<br/>editdiff · editmatch"]
        LSP1["lsp · lsp_client"]
        BROWSER["browser · web_search"]
        EVAL["eval · notebook · debug"]
        IMG["image · image_gen · imageresize"]
        MEMTOOL["memory · recall · retain · reflect"]
        MCPTOOL["mcp_tool（McpRegistry）<br/>mcp.rs:554"]
    end
    subgraph AGENT2["子代理编排 orchestration/"]
        ORCH["OrchestrationRuntime<br/>orchestration/runtime.rs:730"]
        CHILD["ChildSession<br/>orchestration/runtime.rs:57"]
        JOBS["jobs · persistence<br/>工具绑定"]
    end
    subgraph WF["工作流 workflow/ + workflow_worktree/"]
        WFM["WorkflowManager<br/>workflow/manager.rs:196"]
        WFS["WorkflowSupervisor<br/>workflow/supervisor.rs:283"]
        WFT["worktree overlay<br/>workflow_worktree/mod.rs:280"]
    end
    subgraph EXT["扩展与集成"]
        EXT1["extensions.rs<br/>ExtensionSpec:564 · 进程/QuickJS"]
        QJS["quickjs_host.rs<br/>QuickJsExtensionHost:630"]
        PLUGIN["plugin.rs 市场"]
        PKG["packages.rs 包资源"]
        HOOKS["hooks.rs HostHooks:71"]
    end
    subgraph CFG["配置 · 安全 · 隔离"]
        SET["settings.rs · settings_catalog.rs<br/>RuntimeSettingsSnapshot:517"]
        AUTH["auth.rs AuthManager:921"]
        TRUST["trust.rs TrustStore:172<br/>resolve_project_trust:362"]
        SANDBOX["sandbox.rs SandboxConfig:48"]
        ENC["encrypt.rs · oauth.rs"]
    end
    subgraph CTX["上下文与选择"]
        SEL["selector.rs SelectionPlan:321"]
        RES["resources.rs · resource_manager.rs<br/>ResourceManager:317"]
        MEM["memory.rs MemoryConfig:588"]
        SYS["system_prompt.rs · prompt_templates.rs"]
    end
    subgraph DUR["持久化 · 生命周期"]
        COMP["compaction.rs 压缩/回退"]
        SCAT["session_catalog/ 会话树"]
        LOOP1["loop_scheduler.rs LoopTask:97"]
        GOAL["goal.rs · handoff.rs · todo.rs"]
    end
    APP1 --> SESS1
    SESS1 --> STORE
    SESS1 --> TOOLS
    SESS1 --> CTX
    SESS1 --> AGENT2
    AGENT2 --> WF
    APP1 --> EXT
    EXT --> QJS
    EXT --> PLUGIN
    EXT --> PKG
    APP1 --> CFG
    CFG --> AUTH
    CFG --> TRUST
    CFG --> SANDBOX
    SESS1 --> DUR
    DUR --> COMP
    DUR --> SCAT

图 2 — 单回合运行时流水线（Sequence）

sequenceDiagram
    autonumber
    actor U as 用户
    participant AP as "Application<br/>application.rs:1402"
    participant SE as "Session<br/>session.rs:3685 run()"
    participant AG as "pi-agent Agent<br/>agent.rs / loop_runtime.rs"
    participant PR as "pi-ai provider<br/>stream"
    participant TL as "Tool 目录<br/>tools.rs"

    U->>AP: prompt(text)
    AP->>SE: run(prompt)
    SE->>SE: run_messages(messages)
    SE->>SE: inject_selection_messages()<br/>selector 选择 + memory 注入
    SE->>SE: begin_run() → ClaimedRun
    SE->>SE: execute_with_retries()<br/>session.rs:3853
    SE->>AG: agent.prompt_messages()
    AG->>AG: run_agent_loop → run_loop
    loop 每个模型回合
        AG->>PR: 流式请求（含工具定义）
        PR-->>AG: assistant 消息 / tool_call
        alt 有工具调用
            AG->>TL: 执行 AgentTool.execute()
            TL-->>AG: ToolResult
            AG->>AG: 工具结果回合继续
        else 无工具调用
            AG-->>SE: 回合结束（stop_reason）
        end
    end
    SE->>SE: finish_run() → 记录/事件
    SE-->>AP: RunResult
    AP-->>U: 渲染结果

图 3 — 回合失败恢复决策（重试 / 回退 / 压缩）

flowchart TD
    A["execute_with_retries<br/>session.rs:3853"] --> B{"最后消息是<br/>Assistant 成功?"}
    B -->|是| Z["返回成功<br/>finish_retry_success"]
    B -->|否| C{"stop_reason == Error?"}
    C -->|否| Z
    C -->|是| D{"context overflow?"}
    D -->|是| E{"已尝试过<br/>overflow 恢复?"}
    E -->|是| F["报错终止<br/>Context overflow persisted"]
    E -->|否| G["自动压缩<br/>perform_compaction(Overflow)"] --> H["继续 agent.continue_run()"] --> B
    D -->|否| I{"retryable 错误<br/>且未超限?"}
    I -->|是| J["重试（RetrySettings）<br/>session.rs RetrySettings:467"]
    J --> B
    I -->|否| K{"有回退链候选?<br/>retry_fallback.rs find_candidates:409"}
    K -->|是| L["切换到回退模型<br/>format_retry_fallback_selector:112"]
    L --> M["continue_run"] --> B
    K -->|否| N["DoomLoopTracker 触发<br/>session.rs:228 → 终止"]
    N --> F

图 4 — pi-agent 循环内部

flowchart TB
    E["run_agent_loop<br/>loop_runtime.rs:45"] --> F["run_loop<br/>loop_runtime.rs:103"]
    F --> G["取 steering / follow-up 消息<br/>PendingQueue"]
    G --> H["组装 AgentContext<br/>types.rs:546"]
    H --> I["调用 stream_fn（pi-ai 流式）"]
    I --> J{"解析回复"}
    J -->|tool_call| K["before_tool_call 钩子"]
    K --> L["执行 AgentTool（AgentTool::execute<br/>types.rs:265）"]
    L --> M["after_tool_call 钩子"]
    M --> N["写入消息历史"] --> I
    J -->|纯文本| O["AgentSettled 事件"]
    J -->|Aborted/Error| O
    O --> P["AgentEvent 广播<br/>types.rs:645"]
    P --> Q["Session 订阅 → ApplicationEvent → TUI"]

图 5 — 工具子系统

flowchart LR
    S["Session.get_active_tools<br/>session.rs:1942"] --> CAT["create_all_tools<br/>tools.rs:537"]
    CAT --> T1["read / grep / find / glob / ls"]
    CAT --> T2["bash（brush 引擎 + ProcessManager）<br/>tools/bash · process/"]
    CAT --> T3["edit / write / ast_edit<br/>tools/ast_grep · editdiff · editmatch"]
    CAT --> T4["lsp / browser / web_search"]
    CAT --> T5["eval / notebook / debug"]
    CAT --> T6["image / image_gen / imageresize"]
    CAT --> T7["memory / recall / retain / reflect<br/>memory.rs"]
    CAT --> T8["mcp_tool → McpRegistry<br/>mcp.rs:656"]
    CAT --> T9["ask / todo / goal"]
    subgraph INFRA["执行基础设施"]
        I1["tool_presentation.rs<br/>结果渲染与卡片"]
        I2["truncate.rs · redact.rs<br/>截断与脱敏"]
        I3["tools/mutation_queue.rs<br/>写操作队列"]
        I4["tools/framing.rs<br/>流式帧"]
    end
    T2 --> INFRA
    T3 --> INFRA
    CAT --> INFRA

图 6 — 子代理编排（Orchestration）

flowchart TB
    APP2["Application / Session"] --> OR["OrchestrationRuntime<br/>orchestration/runtime.rs:730"]
    OR --> CS["ChildSession<br/>runtime.rs:57<br/>（独立 Session 快照）"]
    OR --> CHILDREQ["ChildSessionRequest<br/>runtime.rs:532<br/>（任务 + 预算 + 工具）"]
    OR --> MAIL["MailboxMessage<br/>runtime.rs:618<br/>子代理消息信箱"]
    OR --> DUR2["PreparedDurableBinding<br/>runtime.rs:920<br/>持久化绑定（fail-closed）"]
    OR --> TOOLS2["orchestration/tools.rs<br/>子代理控制工具"]
    CS --> SNAP["AgentSnapshot · AgentStatus<br/>runtime.rs:573"]
    CS --> RESULT["TaskResult<br/>runtime.rs:709"]
    TOOLS2 --> OR
    DUR2 --> STORE2["session_store 持久子会话<br/>start_durable_child_session_in<br/>session_store.rs:1560"]

图 7 — 工作流（YAML DAG + worktree）

flowchart TB
    WM["WorkflowManager<br/>workflow/manager.rs:196"] --> PARSE["解析 YAML DAG<br/>workflow/detail.rs · store.rs"]
    PARSE --> TASKS["WorkflowTask DAG<br/>WorkflowStatus:54"]
    TASKS --> SUP["WorkflowSupervisor<br/>workflow/supervisor.rs:283"]
    SUP --> AGENTS3["按任务分配子代理<br/>（orchestration ChildSession）"]
    SUP --> TOB["WorkflowSupervisorTodoObservation<br/>supervisor.rs:73<br/>观察 todo 完成度"]
    SUP --> EV3["WorkflowEvent 广播"]
    subgraph WT["worktree 隔离"]
        WTM["WorkflowWorktreeManager<br/>workflow_worktree/mod.rs:280"]
        OVER["overlay.rs 工作树叠加"]
        GIT["git.rs 集成（IntegrateStrategy:209）"]
    end
    WM --> WTM
    WTM --> OVER
    OVER --> GIT
    GIT -->|IntegrateOutcome| WM

图 8 — 扩展 / 钩子 / 信任 / 沙箱 / MCP

flowchart TB
    APPH["ApplicationExtensionHost<br/>application.rs:3067"] --> EXTS["ExtensionSpec<br/>extensions.rs:564"]
    EXTS --> RUNTIME{"runtime 类型"}
    RUNTIME -->|process| PE["ProcessExtensionManifest<br/>extensions.rs:227<br/>子进程扩展"]
    RUNTIME -->|quickjs| QE["QuickJsExtensionHost<br/>quickjs_host.rs:630"]
    PE --> CAP["ExtensionCapabilityManifest<br/>extensions.rs:122"]
    QE --> CAP
    CAP --> PERM["ExtensionPermissionSet<br/>extensions.rs:154"]
    PERM --> TRUSTDEC{"pre_trust_decision<br/>（宿主钩子先行）"}
    TRUSTDEC -->|允许| LOAD["加载并执行扩展<br/>工具 · 事件钩子 · 渲染器"]
    TRUSTDEC -->|拒绝/询问| ASK["Ask 升级为 Trusted<br/>（trust 只能升不能降）"]
    TRUSTDEC --> SANDBOX2["sandbox.rs resolve:499<br/>沙箱配置（cap-std）"]
    PERM --> HOOKS2["HostHooks 事件<br/>hooks.rs:71<br/>before_tool_call 等"]
    PERM --> MCP2["McpRegistry 服务器<br/>mcp.rs:554<br/>stdio 子进程（可禁用）"]
    LOAD --> TOOLP["扩展工具注入 Session 工具目录"]

图 9 — 会话持久化与生命周期

flowchart TB
    START["start_session<br/>session_store.rs:1177"] --> REC["SessionRecorder<br/>session_store.rs:607<br/>（消息 + 工具调用 + 事件）"]
    REC --> FILES["会话文件<br/><repo-digest>/<session-id>/"]
    FILES --> RESUME["resume_session<br/>session_store.rs:1551"]
    FILES --> BRANCH["create_branched_session<br/>session_store.rs:1237"]
    FILES --> FORK["fork_session_in<br/>session_store.rs:1473"]
    REC --> COMP["compaction.rs<br/>（阈值/手动/溢出压缩）"]
    COMP --> REWIND["RewindTarget · RewindOutcome<br/>session.rs:589"]
    COMP --> SNAP["compact_snap 快照压缩<br/>（先落盘+fsync 再引用）"]
    FILES --> SCAT["session_catalog/<br/>会话树 · lineage"]
    REC --> EVENTS["SessionEvent 广播<br/>session.rs:503 → ApplicationEvent:209"]

图 10 — 上下文装配管线（选择器 + 资源 + 系统提示词）

flowchart LR
    REQ["用户请求"] --> SEL["selector.rs<br/>SelectionPlan:321<br/>（autoMode / 分类 / 技能选择）"]
    SEL --> AUTO["PromptMode · AutoMode<br/>selector.rs:82"]
    SEL --> SKILL["加载 skill:// 技能正文<br/>session.rs inject_selection_messages"]
    REQ --> RES["resources.rs / resource_manager.rs<br/>ResourceSnapshot:259<br/>可信项目资源发现"]
    RES --> RELOAD["reload_resources<br/>session.rs:1744"]
    REQ --> MEM["memory.rs<br/>（hindsight 记忆注入）"]
    MEM --> INJ["inject_hindsight_memory"]
    REQ --> SYS["system_prompt.rs<br/>当前系统提示词 session.rs:1991"]
    SYS --> TEMPLATES["prompt_templates.rs"]
    AUTO --> SESS3["Session 回合开始"]
    SKILL --> SESS3
    INJ --> SESS3
    SYS --> SESS3

关键事实索引（可执行验证）

覆盖说明

• 全量阅读：lib.rs 模块导出、session.rs（回合/重试/压缩主路径）、application.rs（状态机与事件）、tools.rs 目录、pi-agent 循环、session_store.rs 持久化、orchestration/runtime.rs、workflow/*、extensions.rs、auth/trust/sandbox 核心类型。
• 摘要阅读（仅结构）：settings.rs、mcp.rs、selector.rs、resource_manager.rs、compaction.rs、plugin.rs、packages.rs、markdown/*。
• 未逐行展开：各 tools/* 内部实现、tests.rs、session_catalog/tests.rs。

Configuration profiles, TOML settings, and scoped auth

This page covers the configuration surfaces beyond plain settings.json: config profiles, TOML settings files, environment expansion inside settings, scoped credentials, and opt-in stateful Responses chaining.

Config profiles (--profile)

--profile is a global flag that relocates the user base directory — agent dir, sessions, settings, auth, memory, skills — to <base>/profiles/<name>. default keeps the default base; PI_PROFILE is honored when the flag is absent (crates/pi-cli/src/args.rs:87-92).

rpi --profile work sessions
rpi sessions --profile work        # global flag: accepted after subcommands
PI_PROFILE=work rpi                # environment equivalent

• Name rules: 1–64 ASCII letters, digits, -, or _ (default is valid and selects the default profile); whitespace is trimmed first. Anything else (slashes, dots, spaces, non-ASCII) fails with an actionable error (validate_profile_name in args.rs:231-249).
• Each profile has its own settings.json, auth.json, models.json, trust.json, skills/, sessions/, and resource trees — profile isolation is by directory, so credentials, trust decisions, and memory never leak between profiles.

TOML settings

Each scope's settings file is chosen deterministically by name, never by content sniffing: a settings.toml sitting next to the canonical settings.json wins when present; otherwise the canonical JSON file is used. A .toml extension selects TOML parsing/serialization; any other extension (or none) selects JSON (crates/pi-coding/src/settings.rs:2277-2299).

• TOML files round-trip through the typed Settings struct; unknown fields are retained in the extra maps, so mixed-format documents survive a settings write.
• Settings writes target whichever file the loader would read (JSON→JSON, TOML→TOML).
• TOML has no null: JSON nulls inside retained extra maps are dropped on serialization; datetimes become their string form.

# settings.toml next to settings.json wins
defaultProvider = "openai"
defaultModel = "openai/gpt-5"
approvalMode = "write"

[orchestration]
tasks = true
maxConcurrency = 8
isolation = "worktree"

[memory]
backend = "local"

[mcp_servers.my-tools]
transport = "stdio"
command = "npx"

Environment expansion in settings

$NAME and ${NAME} references in every string value of the settings document are replaced with the matching process-environment value, recursively through nested objects and arrays (including retained unknown fields). Keys and non-string values are never expanded (expand_env_in_value_with in settings.rs:2375-2439).

Important properties:

• Expansion applies only when projecting the effective runtime view (SettingsManager::settings, consumed by sessions). The persisted layers keep the raw references, so writing settings never persists expanded secrets (e.g. mcpServers[].env tokens).
• Unset names are left verbatim (fail-open) and reported once per name through the settings diagnostic channel; there is no default-value syntax.
• Expansion is recursive over the runtime view only; the persistence view keeps literals.

{
  "mcpServers": [
    { "name": "local", "command": "$MCP_CMD", "args": ["-y", "${MCP_PKG}"] }
  ],
  "sandbox": { "allowedPaths": ["$PROJECT_ROOT", "${CACHE_DIR}/pi"] }
}

Scoped credentials (--scope)

rpi login and rpi logout accept a scope label:

rpi login anthropic --scope work
rpi login anthropic --scope personal
rpi logout xai --scope personal

The active scope is PI_AUTH_SCOPE (environment) or settings.authScope (settings.rs:911-915). A scoped credential is selected over the unscoped default when the active scope matches its label, which lets one machine hold multiple credentials per provider (work vs. personal) and pick between them per project or per shell.

Opt-in stateful Responses chaining

responsesStatefulChain (settings.rs; default false) opts into stateful turn chaining for OpenAI Responses API models (crates/pi-ai/src/providers/responses.rs:30-43): the provider keeps the previous response id per session and sends it as previous_response_id on the next turn, sending only the new input items instead of the full conversation history.

• While enabled, every response is stored server-side (store: true) — both the seed response and each chained response — because the provider must resolve previous_response_id from stored responses. Stateless mode (store: false) never chains.
• The chain is per session in process memory (a session resumed from disk starts fresh — the stored id would not match a foreign transcript). It breaks (falls back to full history) after consecutive failures or when the session transcript is replaced wholesale (compaction resets it, reset_responses_chain).
• Ignored by every other provider.

Invariants

• Profile names are validated before any use; default and empty select the default base, and profile isolation is by directory (no cross-profile credential/trust leakage).
• Settings file format is name-determined, never sniffed; a .toml extension always parses as TOML.
• Environment expansion never mutates the persisted document — expanded secrets cannot be written back.
• Scoped credentials only ever add a labeled choice; the unscoped default remains for providers/sessions without a matching scope.

Related documentation

• settings-trust.md — settings.json fields and trust
• authentication.md — credential precedence
• environment-variables.md — PI_PROFILE, PI_AUTH_SCOPE, and all env vars

Environment variables

This page lists every environment variable that rpi reads from source. Values are never documented here; set them in your shell or agent configuration. The lists are grouped by function rather than priority.

Installer / updater

Runtime configuration

PI_CODING_AGENT_DIR is the only way to relocate the agent tree; the current working directory is never trusted as a fallback. SESSIONS_HOME relocates only the session subtree — agent configuration, skills, and resources remain under PI_CODING_AGENT_DIR (or $HOME) when only SESSIONS_HOME is set. Precedence for the session store root is PI_CODING_AGENT_DIR > $SESSIONS_HOME/.pi/agent > $HOME/.pi/agent.

Local model configuration

Tool environment

The bash tool receives the parent process environment with these additions:

Parent-process values for these keys are stripped before the additions are applied, so stale values never leak into a child.

Provider API keys

These variables are read by rpi to authenticate provider requests. Empty values are treated as unset.

Precedence notes:

• Anthropic: ANTHROPIC_OAUTH_TOKEN wins over ANTHROPIC_API_KEY. ANTHROPIC_AUTH_TOKEN is used as a bearer header and is never returned as an API key.
• Amazon Bedrock: ambient AWS credentials (shared config files, instance metadata, etc.) are intentionally not read. Only the listed environment variables are considered.
• Google Vertex: ADC files and credential helpers are not read. Use GOOGLE_CLOUD_API_KEY, GOOGLE_CLOUD_ACCESS_TOKEN, or an authorization header.

Azure OpenAI configuration

In addition to AZURE_OPENAI_API_KEY:

AWS Bedrock configuration

See the provider API-keys table above for the credential variables.

Google Vertex configuration

Anthropic cache retention

Cloudflare placeholders

For Cloudflare Workers AI and AI Gateway models.json baseUrl values may contain:

{CLOUDFLARE_ACCOUNT_ID}  — from env CLOUDFLARE_ACCOUNT_ID
{CLOUDFLARE_GATEWAY_ID}  — from env CLOUDFLARE_GATEWAY_ID

They are replaced at request time before the URL is used. If a placeholder is present and the matching variable is unset, the request fails.

OAuth tuning

Extension host

Session import

Editor / clipboard / display

Template expansion

auth.json and models.json values may use these forms:

For auth.json credentials, variables are also resolved from the optional per-credential env map. models.json values use only the process environment (and, for OAuth-stored credentials, the credential's own env). Unset variables produce an error; there is no default-value syntax. Command-valued values (!command) are rejected for API keys and headers.

Sandbox and overlayfs isolation

This page documents the two Linux confinement/isolation layers: the filesystem sandbox for process spawns (bash, process extensions, and orchestration subagents) and the overlayfs isolation backend used by workflow checkouts.

Filesystem sandbox

The sandbox (crates/pi-coding/src/sandbox.rs) is an opt-in Linux filesystem sandbox for process spawns. It is confinement, not isolation: the command still runs as the same user with the same privileges, but inside fresh Linux namespaces (unshare) so that

• only the configured allowed paths are visible (bind-mounted read-write, or read-only when sandbox.readOnly is set),
• everything else on the host filesystem is denied (tmpfs root + pivot_root),
• the command gets a private, empty HOME and TMPDIR under the sandbox root instead of the host home (codex/claude parity),
• the network is off by default (fresh net namespace, loopback only),
• /proc reflects only the sandbox's own PID namespace.

System binaries and libraries under /usr, /bin, /sbin, /lib, /lib64 are bind-mounted read-only so commands can execute; user data under those roots is still hidden. Denied paths are overlaid with an empty tmpfs mount so they are invisible even when nested inside an allowed path.

Requirements: Linux and the unshare command (util-linux). Unprivileged users additionally need user namespaces (kernel.unprivileged_userns_clone or equivalent); the wrapper maps the caller to root inside the namespaces only — there is no privilege escalation on the host. On non-Linux targets every sandbox entry point returns an explicit "sandbox unsupported on this platform" error.

Settings

{
  "sandbox": {
    "enabled": true,
    "network": false,
    "readOnly": false,
    "allowedPaths": ["<workspace>", "<data-root>"],
    "deniedPaths": ["<workspace>/secrets"]
  }
}

deniedPaths wins over allowedPaths (denied overlays come last in the mount order). The working directory must live inside an allowed path, otherwise its inode would be detached after pivot_root.

What the sandbox covers

• bash tool — when settings.sandbox.enabled is set, bash commands run through run_in_sandbox (streaming merged output, timeout, abort; the whole process group is killed on either so namespaced descendants cannot linger).
• Process extensions — long-lived protocol children can be spawned with spawn_piped (same fail-closed validation and allowed/denied path semantics).
• Orchestration subagents — with settings.orchestration.sandboxed = true, every process a child spawns (its bash tool) is confined to the workspace, the agent directory, and sandbox.allowedPaths (settings.rs:318-325).

The environment inside the sandbox is fully controlled by the caller (env is applied after env_clear); the sandbox path lists are appended last so a host environment can never spoof them.

Invariants

• Every sandboxed spawn validates its configuration fail-closed before the unshare wrapper is constructed.
• Setup is PID 1 of the fresh namespaces and fails closed: every step exits with a distinct code and an actionable message on stderr.
• The sandbox never escalates privileges: the caller is mapped to root only inside the user namespace, and the host uid is unchanged.

Overlayfs isolation

crates/pi-coding/src/isolate.rs provides an overlayfs isolation backend (OMP pi-iso parity): a writable "merged" view over a read-only "lower" tree without a deep copy. OverlayfsIsolation::start materializes merged as the union of lower (read-only) and upper (private, writable copy-on-write); stop detaches the mount (umount -l) and cleans the upper/work directories.

Backend fallback chain, tried in order until one succeeds (OverlayBackend):

1. Kernel overlay — mount -t overlay -o lowerdir=,upperdir=,workdir=. Requires mount privilege: real root, or a user namespace that owns the process mount namespace.
2. fuse-overlayfs — PATH lookup; runs as a FUSE daemon, works unprivileged and is visible to every process.
3. rcopy — recursive copy of lower into merged; no mount needed.

Backends never degrade silently: the first candidate that succeeds wins and every later candidate is skipped; the copy fallback guarantees callers always get a usable writable view. The chosen backend is serialized by the workflow isolation manager so a restored workflow re-establishes exactly the backend it had before a restart (rcopy must never be re-run over an existing upper, which would clobber the workflow's changes). Timeouts bound hung mounts: 30 s per mount command, 5 s fuse readiness.

Use in workflows

settings.orchestration.isolation = "overlayfs" selects the overlayfs workflow backend (workflow_worktree/overlay.rs): each workflow gets a private overlay whose read-only lower layer is the live source tree and whose writable upper layer is a private per-workflow dir. Integration commits the upper state as a single commit on the source branch — no merge history, no merge-conflict detection; overlayfs integration is last-writer-wins by design, and Conflicted is never produced by this backend. See workflows.md for the isolation options (worktree default, overlayfs, none).

Related documentation

• security.md — path containment and process ownership hardening
• workflows.md — workflow isolation backends
• settings-trust.md — sandbox and orchestration.sandboxed settings

Hooks and trust hooks

Host hooks are external commands that observe (and, for two events, gate) session activity. They are configured under settings.hooks and run by the HostHooks runtime (crates/pi-coding/src/hooks.rs). Extensions additionally receive lifecycle events — including a trust_decision event that can recommend approving a tentative project trust decision.

Host hooks

{
  "hooks": [
    { "event": "pre_tool_call", "matcher": "read", "command": ["/opt/hooks/guard", "--strict"], "timeoutMs": 1200, "failClosed": true },
    { "event": "session_end", "command": ["/opt/hooks/bye"] }
  ]
}

HookConfig fields (settings.rs:731-757):