CodeVetter · Repo Unpack evidence
earendil-works/pi
github.com/earendil-works/pi ↗ · 1822 files · 17.2 MB
New issues and PRs from new contributors are auto-closed by default.
Overview
Pi is a TypeScript monorepo for the 'Pi agent harness', published as the `pi` CLI (@earendil-works/pi-coding-agent): a self-extensible terminal coding agent with read/bash/edit/write/grep/find/ls tools, JSONL session persistence under ~/.pi/agent, and a TypeScript extension system loaded via jiti. It is built on in-house libraries: pi-agent-core (event-sourced agent loop), pi-ai (unified LLM API with 41 built-in providers plus OAuth flows), pi-tui (differential-rendering terminal UI with native modules), plus an experimental distributed stack (chord composition runtime, durable runtime, CBOR protocol/client/server, sqlite session backend). Notably it deliberately ships no sandbox — security relies on project-trust gating of project-local resources and external containerization.
System map
npm-workspaces monorepo (packages/*, plus packages/session-backends/* and extension examples) built in dependency order by the root build script: chord → tui → telemetry → ai → durable → agent → session-backends/sqlite-node → protocol → client → server → coding-agent. The shippable product is packages/coding-agent whose bin `pi` runs dist/bundle/cli.js (bundled from src/cli.ts → src/main.ts) on Node >=22.19, with an alternative Bun-compiled binary path. The agent runtime lives in pi-agent-core, provider access in pi-ai, terminal rendering in pi-tui (with C native modules per platform), and an experimental RPC/session-server stack in protocol/client/server/durable. State lives in ~/.pi/agent (auth.json, settings.json, models.json, sessions/, themes/, prompts/, bin/).
- Root package.json defines workspaces covering packages/*, packages/session-backends/*, and several coding-agent extension examples; the `build` script chains package builds in explicit dependency order ending at coding-agent.
- CLI entrypoint is packages/coding-agent/src/cli.ts, a 6-line shim that calls setupCli() then main(process.argv.slice(2)); the published bin `pi` points at dist/bundle/cli.js produced by scripts/build-coding-agent-bundle.mjs via the `build` script.
- main() in packages/coding-agent/src/main.ts is the single dispatcher: auth subcommands, package commands (install/remove/update/list), config command, then parseArgs, migrations, SessionManager creation, AgentSessionRuntime creation, and finally mode dispatch to runRpcMode, InteractiveMode, or runPrintMode.
- resolveAppMode selects between four run modes — rpc, json, print, interactive — from --mode/--print flags and stdin/stdout TTY detection; piped stdin forces print mode.
- packages/agent (pi-agent-core) exposes the Agent class and the lower-level agentLoop/runAgentLoop functions plus a harness/ subtree (pico3 session runtime, lane scheduler, session backends) that powers the experimental server packages.
- packages/ai (pi-ai) registers 41 built-in LLM providers in builtinProviders() (anthropic, openai, openai-codex, google, google-vertex, amazon-bedrock, github-copilot, openrouter, deepseek, groq, mistral, xai, zai, kimi-coding, moonshotai, minimax, cerebras, fireworks, together, huggingface, nvidia, baseten, meta, opencode, vercel-ai-gateway, cloudflare variants, qwen/xiaomi token plans, ant-ling, radius) backed by the generated MODELS catalog.
- Sessions are append-only JSONL trees under ~/.pi/agent/sessions/<encoded-cwd>/ named <timestamp>_<sessionId>.jsonl; the current on-disk format is CURRENT_SESSION_VERSION = 3.
- User state roots at getAgentDir() = $PI_CODING_AGENT_DIR or ~/.pi/agent, which holds auth.json, settings.json, models.json, sessions/, themes/, prompts/, tools/, bin/, and the debug log; PI_CODING_AGENT_SESSION_DIR can redirect sessions.
- packages/tui is a standalone terminal UI library (differential rendering, editor component, overlays, markdown/latex) with platform-specific native modules under packages/tui/native/{darwin,linux,win32} plus clipboard.h/napi.h — the source of the repo's C files.
- The experimental distributed stack: pi-protocol defines a version-handshaken, CBOR-framed envelope protocol (4-byte big-endian length prefix) over byte transports; pi-server hosts routed server/Session services; pi-client is the transport-neutral client; pi-durable provides durable record contracts with an in-memory storage reference.
- chord is a standalone application-composition runtime (facets, typed services, replicated state, RPC boundary) that intentionally depends on no other Pi workspace package; durable's Pico runtime and agent's harness/ build on its concepts.
- session-backends/sqlite-node provides SqliteSessionRepo, a node:sqlite-backed Session repository for pi-agent-core's harness session abstraction — one .sqlite file per Session under a directory.
Feature catalog
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.
Data flow
A prompt enters via CLI args, piped stdin, or the TUI editor; AgentSession wraps it as a user AgentMessage and hands it to Agent.prompt → runAgentLoop. Per turn the loop transforms AgentMessage[] → LLM Message[] (convertToLlm), streams via the model's provider streamFn, executes toolCall content blocks through tools/extensions, and appends ToolResultMessages. AgentSession subscribes to agent events and persists each message_end to the JSONL session file via SessionManager, while the active mode renders events (TUI components, text, or JSON lines). Credentials come from auth.json (locked, 0600) resolved per-request by ModelRuntime; model catalogs come from generated data + models.json + a remote catalog refresh.
- streamAssistantResponse is the LLM boundary: it applies transformContext (AgentMessage[]→AgentMessage[]), convertToLlm (AgentMessage[]→Message[]), normalizeContext, resolves a fresh API key via getApiKey(provider), then calls streamFn(model, llmContext, options) and folds stream events into a final AssistantMessage.
- runLoop has an outer loop for follow-up messages and an inner loop that alternates: drain steering queue → emit turn_start → prepareRequest hook → stream assistant response → execute tool calls → finishTurn hook → turn_end; the loop ends on agent_end.
- Tool calls from an assistant message run in parallel by default, sequentially if config.toolExecution or any tool's executionMode requires it; each call goes through prepareToolCall (argument validation via validateToolArguments), execution with progress callbacks, and finalizeExecutedToolCall producing a ToolResultMessage pushed into context.
- Persistence path: AgentSession subscribes to agent events; on message_end it calls sessionManager.appendMessage(event.message) which appends a SessionMessageEntry to the JSONL file; model changes, thinking-level changes, usage, compaction, labels, and custom entries get their own entry types.
- Agent state is owned by the Agent class: messages/tools arrays with copy-on-assign setters, pendingToolCalls set, steeringQueue and followUpQueue (PendingMessageQueue with 'all' | 'one-at-a-time' drain modes) polled by the loop via getSteeringMessages/getFollowUpMessages.
- Credential flow: FileAuthStorageBackend reads/writes ~/.pi/agent/auth.json under a proper-lockfile lock (sync retry loop, async 30s stale timeout), always writing with mode 0600; ModelRuntime composes stored credentials, env vars (env-api-keys.ts), and runtime overrides into provider auth.
- Model catalog flow: static MODELS catalog (generated) + per-provider dynamic refresh + user models.json + remote catalog provider compose into ModelRuntime; resolveModelScope expands --models/settings enabledModels patterns into ScopedModel list used for selection and Ctrl+P cycling.
- Settings are layered: global ~/.pi/agent/settings.json deep-merged with project .pi/settings.json (deepMergeSettings recurses into nested objects); project settings only load when the project is trusted.
- Context files flow into the system prompt: loadContextFileFromDir checks AGENTS.override.md, AGENTS.md, AGENTS.MD, CLAUDE.md, CLAUDE.MD per directory; loadProjectContextFiles walks ancestors from cwd plus the global agent dir, with git-worktree shadowing handled by findShadowedContextFile.
- Extension events flow through ExtensionRunner (built on an EventBus): AgentSession emits lifecycle events (session_start, turn_start, message_*, tool_*, context, session_compact, ...) which extension handlers observe or mutate; handler errors route to onError listeners rather than crashing the session.
- Output boundaries: interactive mode renders via pi-tui components through InteractiveMode; print mode writes final text or toJsonEvent JSON lines via writeRawStdout (stdout is taken over so extension noise doesn't corrupt the stream); RPC mode serializes responses/events as JSONL on stdout.
- Session reload after compaction or /reload rebuilds state from disk: SessionManager.buildSessionProjection folds entries into messages (skipping compacted ranges via firstKeptEntryId), then the agent context is replaced — this is why CompactionEntry stores the full systemMessage snapshot.
Behavior traces
Three flows dominate. Startup: cli.ts → setupCli → main → auth/package/config short-circuits → parseArgs → runMigrations → SettingsManager → SessionManager (create/open/fork/resume) → createAgentSessionRuntime (settings+resourceLoader+modelRuntime+AgentSession) → theme init → mode dispatch. Prompt turn: session.prompt → Agent.prompt → runAgentLoop → streamAssistantResponse → executeToolCalls → agent_end → persisted + rendered. Persistence: every agent event message_end is appended to the session JSONL by AgentSession's subscriber.
- Startup order in main(): runAuthCommand → Windows self-update quarantine cleanup → cleanupManagedInstall → bootstrap SettingsManager + applyHttpProxySettings/configureHttpDispatcher → handlePackageCommand → handleConfigCommand → parseArgs → --version/--export exits → resolveAppMode → takeOverStdout for non-interactive → validateForkFlags/validateSessionIdFlags → runMigrations.
- Startup continued: startup SettingsManager → optional first-time setup → resolve sessionDir (flag > PI_CODING_AGENT_SESSION_DIR > settings) → createSessionManager → ProjectTrustStore → createRuntime factory → createAgentSessionRuntime → setCapabilityOverrides → initTheme → dispatch to runRpcMode / InteractiveMode.run / runPrintMode.
- createSessionManager branches: --no-session/help/list-models → SessionManager.inMemory; --fork → resolveSessionPath + SessionManager.forkFrom; --session → open or cross-project fork prompt; --resume → selectSession picker; --continue → continueRecent; else SessionManager.create with optional --session-id.
- Runtime creation (createRuntime factory): resolve project trust (cached per-cwd, trustStore, or resolveProjectTrusted prompt for trust-requiring resources) → SettingsManager.create(cwd, agentDir, {projectTrusted}) → createAgentSessionServices (settings, modelRuntime with 15s refresh timeout, resourceLoader) → resolveModelScope → buildSessionOptions → createAgentSessionFromServices.
- Print-mode prompt flow: runPrintMode → rebindSession binds extensions (mode 'print'/'json') and subscribes events → session.prompt(initialMessage) → Agent.prompt → runPromptMessages → runWithLifecycle → runAgentLoop emitting agent_start/turn_start/message events → JSON events streamed via toJsonEvent or final text printed → killTrackedDetachedChildren on SIGTERM/SIGHUP → exit code.
- Single agent turn: runAgentLoop emits agent_start + turn_start + message_start/end for the prompt → runLoop drains steering queue → prepareRequest → streamAssistantResponse (emits message_update deltas) → on done, toolCalls filtered from content → executeToolCalls → tool_results pushed → finishTurn → turn_end → loop repeats until no tool calls, no queued messages → agent_end with newMessages.
- Tool-call safety path: if the assistant message stops with stopReason 'length', failToolCallsFromTruncatedMessage converts every toolCall into an error ToolResultMessage instead of executing possibly-truncated arguments; otherwise prepareToolCall validates args before execution.
- Bash tool execution: createLocalShellOperations.exec → fsAccess check on cwd → spawn(shell, args or stdin-transported command, {detached: !win32}) → trackDetachedChildPid → stream stdout/stderr via onData → timeout/abort → killProcessTree → exit code reported as {exitCode}, null treated as failure.
- Persistence trace: emit(message_end) → AgentSession._handleAgentEvent → sessionManager.appendMessage → appendFileSync on <timestamp>_<id>.jsonl under sessions/<encoded-cwd>/ → entry gets id + parentId forming the session tree → later builds projections via buildSessionProjection for context rebuild.
- Auto-compaction trace: after a turn, AgentSession checks shouldCompact(contextTokens, contextWindow, settings) → spawns compaction under _autoCompactionAbortController → prepareCompaction + compact() calls the LLM to summarize (SUMMARIZATION_SYSTEM_PROMPT, serialized conversation, file-op extraction) → CompactionEntry appended → session context reloaded.
- Session replacement flows (new/fork/switch/import/reload) go through AgentSessionRuntime: tear down current services (emitSessionShutdownEvent), run the createRuntime factory for the new cwd/sessionManager, then rebindSession so the active mode re-subscribes and re-binds extensions.
- RPC session: rpc-entry.ts → main(['--mode','rpc']) → runRpcMode → takeOverStdout → attachJsonlLineReader on stdin → dispatch RpcCommand (prompt/steer/set_model/bash/...) → session events serialized as JSONL responses + extension_ui_request dialogs awaited via pendingExtensionRequests map keyed by UUID.
Testing signals
Vitest is the primary framework (packages/coding-agent/test ~297 files, agent+ai ~240 combined), plus node:test for packages/tui and scripts/*.test.mjs. A faux provider (pi-ai providers/faux.ts) enables deterministic agent-loop testing without API keys, and test/suite/harness.ts builds full AgentSession fixtures. ./test.sh runs the whole suite in a scrubbed environment (temp HOME, no API keys) because e2e tests activate when real endpoint/auth env vars exist. CI runs build → check → npm test on ubuntu; supply-chain checks (pinned deps, shrinkwrap, lockfile gate) run in npm run check and the husky pre-commit hook.
- ./test.sh runs `env -i` npm test with a mktemp HOME, empty git config, disabled git prompts, PI_NO_LOCAL_LLM=1, and AWS_EC2_METADATA_DISABLED — deliberately stripping all credentials so tests never hit real providers; cleanup refuses to rm -rf unverified directories.
- AGENTS.md forbids running the raw vitest suite because it includes e2e tests that activate when endpoint/auth env vars are present; prescribed: ./test.sh, per-file vitest via node_modules/vitest CLI, or node --test for packages/tui.
- The coding-agent suite harness (test/suite/harness.ts) creates a real AgentSession + SessionManager + SettingsManager + AuthStorage in a temp dir and registers the faux provider (registerFauxProvider from pi-ai/compat) with scripted FauxResponseStep lists, so session behavior is tested end-to-end without network.
- packages/coding-agent/test contains ~297 test files covering session branching, compaction, retry, dynamic tools/providers, extensions, args parsing, auth storage, clipboard, keybindings, Windows quirks, plus a regressions/ subdir.
- packages/agent has three vitest configs: default unit tests, vitest.harness.config.ts for harness/session conformance tests (test/harness/memory-conformance.test.ts runs a conformance suite over session storage implementations), and vitest.benchmark.config.ts for session benchmarks.
- packages/tui tests use node:test (editor, keybindings, overlay, markdown, fuzzy, layout, plus regression files for CJK width, SIGWINCH, regional indicators) alongside bench scripts like alt-screen-large-transcript-bench.ts.
- scripts/*.test.mjs run via `node --test` under test:scripts and cover repo tooling: check-runtime-deps, coding-agent-consumer, publish-release-announcement, sync-versions.
- packages/evals is a separate vitest-evals harness: *.eval.ts host evals and *.docs.eval.ts documentation-lift comparisons run in docker containers, requiring PI_PROVIDER/PI_MODEL — it is opt-in and not part of npm test.
- CI (.github/workflows/ci.yml) is a single job: checkout → setup-node 22 → apt deps (cairo/pango/jpeg/gif/rsvg for native builds, fd, ripgrep) → npm ci --ignore-scripts → npm run build → npm run check → npm test, on ubuntu-latest only.
- npm run check is the gate: biome check --write --error-on-warnings, pinned-dep verification, runtime-dep check, TS relative-import check, entry-graph check, shrinkwrap --check, install-lock --check, tsgo --noEmit, and a browser smoke check.
- The husky pre-commit hook runs scripts/check-lockfile-commit.mjs (blocks lockfile commits unless PI_ALLOW_LOCKFILE_CHANGE=1), then full npm run check, then a browser smoke test when staged files touch packages/ai, packages/web-ui, or the lockfile.
- Coverage gaps: real provider streaming paths, OAuth flows, and end-to-end interactive TUI behavior are only exercised when env keys exist or via manual tmux testing documented in .pi/skills/interactive-testing.md — most CI runs exercise mocks. (inferred)
Risk map
The dominant risk is intentional: pi is an unsandboxed local agent whose bash/edit/write tools and jiti-loaded extensions run with full user privileges — the docs state this plainly and point to containerization instead. Concrete hotspots: auth.json holds plaintext credentials (mitigated by 0600 + locking); the extension/package system executes third-party code gated only by project trust for project-local sources; RPC/protocol layers have no peer authentication; and giant files (agent-session.ts 4023 lines, interactive-mode.ts 6851 lines, package-manager.ts 2699 lines) concentrate blast radius.
- No built-in sandbox: docs/security.md states built-in tools can read/write files and run shell commands with the pi process's permissions, and extensions run with the same permissions — isolation is delegated to containers/VMs (docs/containerization.md).
- auth.json stores OAuth/API credentials in plaintext JSON under ~/.pi/agent; writes use mode 0600 and a proper-lockfile lock, but any process running as the user (including extensions and bash commands) can read it.
- Extension loader uses jiti to execute arbitrary TypeScript from user dirs, project dirs, npm/git packages, and -e flags; aliases map @earendil-works/*, legacy @mariozechner/* names, and typebox into the host's own modules — so extensions share the host process and its privileges entirely.
- Project trust is the only input-loading guard: .pi/settings.json, .pi/{extensions,skills,prompts,themes}, .pi/SYSTEM.md, and .agents/skills require trust before loading; non-interactive modes never prompt, so defaultProjectTrust 'ask'/'never' skips them — meaning a config mistake can silently auto-trust or a repo's context files (AGENTS.md/CLAUDE.md) always load regardless.
- The bash tool spawns real shells with detached process groups and tracks detached PIDs for killProcessTree; shellCommandPrefix and custom shellPath settings let projects/users alter every command — a footgun if a trusted-but-malicious project sets them.
- Package manager installs npm/git sources into the agent dir and can self-update the pi binary (with Windows quarantine handling); supply-chain mitigations exist (exact-pinned direct deps, min-release-age=2, npm-shrinkwrap for the published CLI, lifecycle-script allowlist in shrinkwrap generation) but the installed packages still execute as the user.
- RPC mode exposes full session control (bash, prompt, fork, switch_session) on stdin/stdout with no authentication — it trusts whoever spawned it; the experimental pi-protocol README explicitly states peer authentication is not implemented by the transport.
- Blast-radius hotspots: agent-session.ts (4023 lines) mixes session lifecycle, extension dispatch, compaction, retry, bash, export; interactive-mode.ts (6851 lines) is the entire TUI; package-manager.ts (2699 lines) does network + fs + spawn — regressions in these files affect every mode. (inferred)
- Truncated tool calls are a real corruption vector deliberately mitigated: when stopReason is 'length', all tool calls are failed with a re-issue error rather than executed, because the JSON salvage parser can produce arguments that validate but are silently incomplete.
- main() calls process.exit() deep inside helper flows (validateForkFlags, createSessionManager error paths, handlePackageCommand) which complicates embedding and can skip cleanup; a comment notes Windows requires natural drain after `pi update` due to a Node fetch() teardown bug.
- models.generated.ts and image-models.generated.ts are machine-generated from live provider catalogs; editing them directly is forbidden — regeneration can pull unrelated upstream metadata changes into a diff, which is explicitly accepted.
- Git safety rules exist because concurrent pi sessions work in one repo: AGENTS.md forbids git add -A, reset --hard, stash, clean -fd, and --no-verify; the pre-commit hook additionally blocks lockfile changes without PI_ALLOW_LOCKFILE_CHANGE=1.
Extension points
Pi's core is deliberately minimal — CONTRIBUTING.md says features that don't belong in core should be extensions. The main seam is the ExtensionAPI: TypeScript modules loaded by jiti from user/project dirs, CLI -e, settings, or npm/git packages, which can register tools, slash commands, providers, CLI flags, keybindings, UI widgets/renderers, and ~35 lifecycle event handlers. Lower-level seams: pluggable tool Operations (e.g. BashOperations for remote execution), Provider registration in pi-ai, Chord facets/services for the experimental stack, skills/prompt-templates/themes as data resources, and custom session entries for extension persistence.
- ExtensionAPI is the central registry: on() subscribes to ~35 typed events (project_trust, session_start, session_compact, context, before_provider_headers, after_provider_response, agent_start/end, turn_start/end, message_*, tool_execution_*, tool_call, tool_result, user_bash, input, model_select, thinking_level_select, ui_prompt_start/end, agent_settled, session_tree, session_shutdown, session_info_changed).
- Extensions register LLM-callable tools via registerTool (typebox-schema params, execute callback, optional renderers), user commands via registerCommand, and providers via registerProvider(name, ProviderConfig)/unregisterProvider — with doc-commented examples for corporate proxies.
- Extensions are discovered from: ~/.pi/agent paths, project .pi/extensions, settings extensions[] arrays, CLI -e, package-managed npm/git sources, and InlineExtension factories passed programmatically; loading uses jiti with module aliases or embedded virtual modules in compiled-binary mode.
- Built-in tools accept pluggable Operations interfaces — BashOperations.exec can delegate to SSH or a micro-VM (the Gondolin example extension does exactly this), and EditOperations/ReadOperations etc. follow the same pattern.
- ~70 example extensions under packages/coding-agent/examples/extensions demonstrate every seam: tools.ts, commands.ts, subagent/, plan-mode/, permission-gate.ts, sandbox/, gondolin/, ssh.ts, custom-provider-anthropic/, todo.ts, handoff.ts, confirm-destructive.ts, protected-paths.ts — doubling as living documentation.
- Skills (Markdown + frontmatter) and prompt templates are pure-data extension points discovered from .pi/skills, .agents/skills ancestors, and configured paths; themes are JSON files with a validator hook (setThemeJsonValidator) that hosts can replace.
- Extensions can persist state in the session file via CustomEntry (customType namespaced data, excluded from LLM context) and inject context via CustomMessageEntry — documented in the session-manager type comments.
- CLI flag extension: unknown flags are collected into parsed.unknownFlags and passed to the runtime as extensionFlagValues, so extensions can define their own --flags which appear in printHelp output.
- pi-ai's Models registry is itself an extension point: setProvider() adds a Provider implementation to the mutable registry; the coding-agent composes configured, extension-registered, and remote-catalog providers through provider-composer.
- The agent loop exposes hooks for hosts: transformContext, convertToLlm, prepareRequest, prepareNextTurn(WithContext), beforeToolCall, afterToolCall, finishTurn, getSteeringMessages, getFollowUpMessages — Agent maps these to public constructor options.
- In the experimental stack, Chord facets/plugins declare provided/required services that a host validates and activates in dependency order; pi-server's RoutedSessionHandle.invokeService routes opaque service envelopes so new application services plug in without server-side schema changes.
- Stream function is injectable: setDefaultStreamFn lets hosts install a default StreamFn for Agent/agentLoop without pi-agent-core depending on a provider catalog; AgentSession wires ModelRuntime's stream through this seam.
Contributor handoff
AGENTS.md is unusually prescriptive and must be read first: erasable-TypeScript-only syntax (no enums/namespaces/parameter properties — Node strip-only mode), no inline imports, top-level imports only, no `any` unless necessary, no hardcoded key checks (use DEFAULT_*_KEYBINDINGS). After code changes run `npm run check` fully; never run npm run build or npm test unless asked; use ./test.sh or targeted vitest/node --test. Never edit generated files (models.generated.ts); regenerate via scripts. Stage explicit paths only — concurrent pi sessions share the worktree.
- Read first: AGENTS.md (all rules), then packages/coding-agent/src/main.ts (dispatch), src/core/agent-session.ts (session core), src/core/extensions/types.ts (ExtensionAPI), src/core/session-manager.ts (persistence), and packages/agent/src/agent-loop.ts (the loop).
- Code style: tabs with indentWidth 3, lineWidth 120, biome recommended rules; only erasable TypeScript in packages/*/src and test dirs (no enum, namespace, parameter properties, import=) because Node runs sources in strip-only mode during development.
- After code changes run `npm run check` with full output (no tail) and fix all errors/warnings/infos; it runs biome, pinned-dep checks, tsgo --noEmit, entry-graph, shrinkwrap and browser-smoke checks — it does NOT run tests.
- Test commands: ./test.sh for the suite (scrubs env/API keys); single vitest file via node node_modules/vitest/dist/cli.js --run test/x.test.ts from the package root; node --test for packages/tui; harness/suite tests must use test/suite/harness.ts + faux provider — never real provider APIs or paid tokens.
- Changelog convention: per-package packages/*/CHANGELOG.md with fixed [Unreleased] subsections (Breaking Changes/Added/Changed/Fixed/Removed); released sections are immutable; attribution format links to issues/PRs.
- Dependency changes are treated as reviewed code: direct deps pinned exactly (save-exact=true, min-release-age=2), installs use --ignore-scripts, lockfile commits require PI_ALLOW_LOCKFILE_CHANGE=1, and coding-agent shrinkwrap regeneration goes through scripts/generate-coding-agent-shrinkwrap.mjs with an explicit lifecycle-script allowlist.
- Git safety: stage only files you changed (git add <paths>, never -A), check git status first, commit format {feat,fix,docs}[(ai,tui,agent,coding-agent)]: msg, never run reset --hard/checkout ./clean -fd/stash/--no-verify — other pi sessions may share the worktree.
- When fixing a GitHub issue, add a regression test with a comment containing the issue number; when a fix needs a test file, run it and iterate until it passes.
- Trap: models.generated.ts and image-models.generated.ts are generated — edit packages/ai/scripts/generate-models.ts (or generate-image-models.ts) and regenerate instead; the generated diff may include unrelated upstream model metadata and that's acceptable.
- Trap: project trust affects behavior — project-local .pi resources (settings, extensions, skills) silently don't load when untrusted, so tests/manual runs may differ from what a repo's .pi directory suggests; use --approve/-a or --no-approve/-na to control it.
- Trap: session state leaks between runs under ~/.pi/agent (sessions, auth.json, settings.json, models.json); tests must isolate HOME (as test.sh does) or AgentSession will pick up real credentials and sessions.
- The build order matters — root `build` script chains packages explicitly; coding-agent's build also runs scripts/build-coding-agent-bundle.mjs and copy-assets (themes, export-html template, vendor JS) so asset changes need the copy step, not just tsgo.
Languages
| Language | Files | Share of source |
|---|---|---|
| TypeScript | 1506 | 96% |
| Markdown | 158 | docs/config |
| JSON | 48 | docs/config |
| JavaScript | 42 | 3% |
| YAML | 14 | docs/config |
| Shell | 11 | 1% |
| C | 8 | 1% |
| CSS | 1 | docs/config |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (1732 files)
Source layout — packages/
| Path | Files |
|---|---|
packages/coding-agent/ | 238 |
packages/evals/ | 30 |
packages/session-backends/ | 33 |
Repository structure
| Top-level path | Files |
|---|---|
packages/ | 1732 |
scripts/ | 40 |
.github/ | 15 |
.pi/ | 15 |
.husky/ | 1 |
Docs found: AGENTS.mdCONTRIBUTING.mdREADME.md
Package
package.json — pi-monorepo v0.0.3, 9 declared dependencies.
@anthropic-ai/sandbox-runtime@biomejs/biome@types/node@typescript/native-previewesbuildhuskyshxtsxtypescript
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructions.github/workflows/publish-model-catalog.yml— GitHub Actions workflow.github/workflows/issue-gate.yml— GitHub Actions workflow.github/workflows/pr-gate.yml— GitHub Actions workflow.github/workflows/remove-inprogress-on-close.yml— GitHub Actions workflow.github/workflows/build-binaries.yml— GitHub Actions workflow.github/workflows/issue-triage-labels.yml— GitHub Actions workflow.github/workflows/issue-analysis.yml— GitHub Actions workflow.github/workflows/npm-audit.yml— GitHub Actions workflow
Structural health signals
Average score 6.9/10 across 96 analyzed source files; 29 hotspots surfaced.
packages/agent/docs/mobile-handoff/02-plugins/02-sandbox/src/markdown-bundle.js— 1034 lines, score 5 (Large file, Deep nesting)packages/ai/src/api/bedrock-converse-stream.ts— 1344 lines, score 5.5 (Large file, Deep nesting)packages/coding-agent/src/core/export-html/template.js— 1213 lines, score 5.7 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
95fbc04997ea2026-09-22 — docs(coding-agent): update changelog with --mode validation fix (#9877)e40126f578cc2026-09-22 — fix(coding-agent): reject invalid --mode values1a584a7a56eb2026-09-22 — feat(ai,coding-agent): add Grok 4.7 support1b6ddca87ca02026-09-21 — fix(ai): omit empty text parts from multimodal user messages4c8eb393c7322026-09-21 — Add [Unreleased] section for next cycle