Guides

Install the Pi coding agent, authenticate with a subscription or API key, and run your first productive session.

Last updated: Jul 27, 2026

How Pi actually works: the agent loop, built-in tools, context files, model providers, sessions, and the TUI.

Last updated: Jul 27, 2026

How Pi extensions actually work: TypeScript modules, the ExtensionAPI, events, custom tools, and a minimal working example.

Last updated: Jul 27, 2026

How the Pi coding agent stores, lists, resumes, forks, compacts, and exports sessions — covering the JSONL tree format on disk, slash commands (/resume, /tree, /fork, /clone), CLI flags (--session, --fork, --no-session), and search across ~/.pi/agent/sessions/.

Last updated: Aug 7, 2026

How Pi TUI themes are selected (settings.json, /settings, --theme flag), where theme files live (~/.pi/agent/themes, .pi/themes, packaged), what every one of the 51 required color tokens controls, and how to write and package your own theme.

Last updated: Aug 7, 2026

How to take a Pi extension from a local TypeScript file (tested via pi -e) to a versioned npm or git package — covering the pi.extensions package.json field, dependencies vs devDependencies for runtime, npm link, pi install link:, npm publish, git URLs, the extension API surface (ExtensionAPI, registerTool, on('tool_call')), and the trust model for project-local extensions.

Last updated: Aug 7, 2026

How to give the pi coding agent new tools it can call via extension-side registerTool or SDK-side defineTool + customTools, with caveats on permissions, output truncation, file-mutation queueing, and Google-compatible string enums.

Last updated: Aug 11, 2026

A reference guide to every built-in slash command in the pi coding agent — what /login, /resume, /tree, /fork, /clone, /compact, /share do, plus how extensions, skills, and prompt templates register their own /commands alongside the built-ins.

Last updated: Aug 11, 2026

How the pi coding agent routes requests across 40+ built-in providers and their model catalogs: OAuth vs API-key flows, the /model command and Ctrl+P cycling, models.json schema for custom models and modelOverrides, plus pricing tiers and constrained sampling.

Last updated: Aug 12, 2026

How to contribute to the pi coding agent: the auto-close and lgtm gate, the quality bar for issues, the AGENTS.md rules agents must follow, pre-flight npm run check + ./test.sh, lockstep versioning, and the release process.

Last updated: Aug 14, 2026

How the pi coding agent's compaction and branch-summary machinery work — the auto-trigger formula, /compact and /tree slash commands, the structured summary schema, the CompactionEntry and BranchSummaryEntry shapes, the session_before_compact and session_before_tree extension hooks, and the relevant settings.

Last updated: Aug 17, 2026

How to drive the pi coding agent headlessly from any host language: -p / --print for one-shot scripting, --mode json for streaming events to stdout, --mode rpc for stateful multi-turn JSON-RPC over stdio — covering framing rules, the command set, trust handling, environment variables, and CI integration.

Last updated: Aug 18, 2026

Every install path for the pi coding agent — npm with --ignore-scripts, Bun, and Windows npm — plus pi update / pi update --self --force, the experimental v0.84.3 staged managed updates, package pinning, npmCommand wrappers, and defaultTools configuration.

Last updated: Aug 24, 2026

How pi spawns child pi processes for delegated work — the official subagent extension's three modes (single / parallel / chain), agent discovery from ~/.pi/agent/agents/, project-local vs user-scope trust, streaming output, usage tracking, and how third-party projects (pi-flows, dsh-pi-agent, pi-goal-list-loop-audit) extend the same primitives.

Last updated: Aug 27, 2026