Pi Coding Agent Documentation

Pages

1. OverviewWhat pi is, the four run modes, default tools, and the first docs routes for CLI users and embedders.
2. Installationnpm and installer install paths, bin entry, package exports, and verification for @earendil-works/pi-coding-agent.
3. QuickstartInstall, authenticate with API key or /login, start interactive pi, and confirm the default read/write/edit/bash tool surface.
4. Run modesInteractive, print/JSON, RPC, and SDK modes: how each is invoked, entry points, and when to choose them.
5. Agent sessionsSession lifecycle, prompt queue, concurrent behavior, stats, and runtime services that own a conversation turn.
6. Branching and session treesSession branching, tree navigation, cancel-during-compact interactions, and name/event constraints for branches.
7. Context compactionAuto and manual compaction triggers, reasons, retries on stream drop, and interactions with in-flight prompts and RPC.
8. Tools and allowlistsDefault read/write/edit/bash tools, extension tools, allowlist and exclude-tools filters, and blocked-tool termination behavior.
9. AuthenticationAPI keys, OAuth login, credential storage, auth checks, ambient auth, and refresh hang failure modes.
10. Providers and modelsBuilt-in and dynamic providers, scoped model order and refresh, models.json hot reload, and provider-retry message behavior.
11. SettingsSettings load and in-memory reload, stale resource refresh, and merge rules for provider retry and related session options.
12. Context filesHow project context files are discovered and injected into sessions, including SDK wiring for context file inputs.
13. SkillsSKILL.md frontmatter rules, naming constraints, collision precedence, disable-model-invocation, and valid versus rejected skill fixtures.
14. ExtensionsTypeScript extension registration, inline naming, active tools on next turn, OAuth prompt input, and shutdown cleanup contracts.
15. Prompt templatesCustom system prompts and prompt templates as reusable session configuration, with SDK entry points and related prompt tests.
16. Themes and Pi packagesTheme export requirements, package manifest validation, and how shareable Pi packages bundle extensions, skills, templates, and themes.
17. SDKEmbed pi with the package main export: minimal agent construction, full control hooks, custom models, tools, and settings.
18. Session runtimeAgentSessionRuntime services, lifecycle events (settled, start notify, event bus), and embedding sessions without the interactive TUI.
19. RPC modeProcess integration via rpc-entry: command IDs, prompt-during-compaction constraints, JSON stream behavior, and unknown-command handling.
20. CLI referencepi binary flags and argument parsing, auth subcommands, experimental auth entry points, and package bin wiring.
21. Package exportsPublic npm surface for @earendil-works/pi-coding-agent: main, rpc-entry, client exports, bin name, and piConfig.configDir.
22. SDK examplesCopy-paste SDK recipes: minimal agent, custom model, skills, tools, extensions, sessions, settings, and full-control setups.
23. Extension examplesReference extension packages: subagent agents, plan-mode, doom-overlay, dynamic resources skill, and auto-commit-on-exit.
24. TroubleshootingRetry and network failures, credential refresh hangs, SIGTERM cleanup, bash output truncation, and session event settlement issues.