CodeVetter · Repo Unpack · Feature catalog
earendil-works/pi
User-facing surface = the `pi` CLI plus in-session slash commands, extension hooks, and the RPC/JSON embedding protocols. CLI flags cover model/provider/thinking selection, session lifecycle (continue/resume/fork/session-id), tool scoping, resource paths (extensions, skills, prompt templates, themes), export, and offline mode. Interactive mode adds a full-screen TUI with 20+ built-in slash commands; headless modes expose the same session operations as JSON commands over stdin/stdout. Extensions add LLM tools, commands, providers, UI widgets, and event handlers.
- CLI flags parsed in parseArgs include: --print/-p, --mode text|json|rpc, --continue/-c, --resume/-r, --session, --session-id, --fork, --session-dir, --name, --provider/--model/--models, --thinking (off|minimal|low|medium|high|xhigh|max), --api-key, --tools/-t, --exclude-tools/-xt, --no-tools, --no-builtin-tools, --extension/-e, --skill, --prompt-template, --theme/--use-theme, --no-* counterparts, --export, --list-models, --offline, --verbose, and @file positional arguments; unknown flags are collected as potential extension flags.
- Top-level subcommands handled before arg parsing: auth commands (runAuthCommand — login/check/credential printing with --no-refresh and JSON output), `pi config` (interactive settings selector with -l/--local project scope gated on trust), and package commands `pi install|remove|update|list` for npm/git-sourced resource packages.
- Built-in slash commands in interactive mode: /settings /model /tree /thinking /scoped-models /export /import /share /bug /copy /name /session /changelog /hotkeys /fork /clone /trust /login /logout /new /compact /resume /reload /quit.
- Built-in agent tools are read, bash, powershell, edit, write, grep, find, ls — exposed through factory functions (createCodingTools = read+bash+edit+write; createReadOnlyTools = read+grep+find+ls) and selectable via --tools/--exclude-tools/--no-tools.
- The bash tool spawns a configurable shell with detached process groups (Unix) so killProcessTree can terminate whole trees on abort/timeout; command transport can go via argv or stdin depending on shell config, and output is accumulated/truncated with DEFAULT_MAX_LINES/DEFAULT_MAX_BYTES.
- Interactive editor supports a `!` prefix bash mode (tracked via editorBashMode) letting users run shell commands directly; user bash executions go through AgentSession.executeBash and emit the user_bash extension event.
- Session tree navigation: sessions form a tree of entries; /fork creates a new branch from an earlier user message, /clone duplicates at the current position, /tree navigates branches, and navigateTree supports LLM-generated branch summaries (BranchSummaryEntry).
- Context compaction: /compact runs manual compaction; auto-compaction triggers when shouldCompact(contextTokens, contextWindow, settings) passes; compaction generates an LLM summary, records a CompactionEntry with file-operation details (readFiles/modifiedFiles), then reloads the session projection.
- RPC mode exposes session control as JSON commands on stdin: prompt, steer, follow_up, abort, clear_queue, new_session, get_state, set_model, cycle_model, get_available_models, set_thinking_level, compact, set_auto_compaction, set_auto_retry, bash, abort_bash, export_html, switch_session, fork, clone, get_tree, get_messages, get_commands, and more, with correlated responses and streamed events.
- Skills are Markdown files with YAML frontmatter (name <=64 chars, description <=1024, disable-model-invocation) discovered from .pi/skills, .agents/skills ancestor dirs, and configured paths; when enableSkillCommands is on they register as /skill:<name> commands and skill blocks are injected into the user message.
- Provider auth includes OAuth flows with dedicated modules: openai-codex, github-copilot, anthropic, openrouter, kimi-coding, xai, meta, radius, plus device-code and PKCE helpers; /login and /logout manage credentials in auth.json.
- Session export/sharing: --export writes an HTML transcript (exportFromFile with vendored template/CSS/JS); /share publishes a session as a secret GitHub gist viewable at pi.dev/session/#<gist-id>; /import resumes a session from a JSONL file.
- A hidden built-in extension registers a llama.cpp provider (src/extensions/llama) so local models appear alongside hosted providers; PI_NO_LOCAL_LLM disables local-LLM probing in tests.
- Package manager feature: settings `packages` lists npm/git sources; DefaultPackageManager resolves, installs (with version ranges, glob filtering, ignore-file support), and updates extension/skill/prompt/theme packages, with `pi update` handling self-update including a Windows quarantine cleanup.
- Themes are user-authored JSON files validated by validateThemeJson and hot-reloaded by a theme watcher; --use-theme and the /settings UI select them; first-time setup shows a theme picker plus analytics opt-in.