Pi

Pi Coding Agent

Pi is a minimal terminal coding harness. Default tools: read, write, edit, bash, grep, find, ls (configurable via the defaultTools setting since Pi 0.84.2). Modes: interactive (pi), print (pi -p), JSON (--mode json), RPC (--mode rpc), or embedded (createAgentSession()). Sub-agents, plan mode, permission flows, and MCP are intentionally left to extensions and Pi packages. Skill synced with Pi 0.84.2.

Pi's philosophy: adapt Pi to your workflows, not the other way around.

Architecture

Core packages on npm (source: github.com/earendil-works/pi):

File System Layout

~/.pi/agent/                    # Global config dir (PI_CODING_AGENT_DIR overrides)
├── settings.json               # Global settings
├── auth.json                   # Credentials (0600 perms)
├── models.json                 # Custom provider/model definitions
├── keybindings.json            # Keyboard shortcuts
├── extensions/                 # Auto-discovered
├── skills/                     # Auto-discovered
├── prompts/                    # Auto-discovered
├── themes/                     # Custom themes
└── sessions/                   # JSONL session files

<project>/
└── .pi/                        # Project-local config (overrides global)
    ├── settings.json
    ├── extensions/
    ├── skills/
    ├── prompts/
    ├── themes/
    └── agents/                 # Agent definitions (subagent extension)

Key Concepts

• Extensions — TypeScript modules with full system access. Hook into Pi's lifecycle to register tools, intercept calls, add commands, build UI. → references/extensions.md
• Skills — Markdown capability packages (SKILL.md + frontmatter) following the Agent Skills standard. Pi loads names + descriptions into the system prompt; bodies load on demand. → references/skills.md
• Settings — Hierarchical JSON: project .pi/settings.json merges over global ~/.pi/agent/settings.json. → references/settings.md
• Packages — Bundles of extensions/skills/prompts/themes via npm, git, or local paths. Installed with pi install. → references/packages.md
• Project trust — Pi 0.79+ asks before loading project-local settings, resources, and packages; decisions persist in ~/.pi/agent/trust.json. --approve/--no-approve override per run; defaultProjectTrust sets the non-interactive fallback. → references/settings.md
• Context files & prompt templates — Pi loads AGENTS.md / CLAUDE.md from the agent dir and from cwd up through ancestors. Per-directory AGENTS.override.md (Pi 0.84.0) replaces same-directory context files while others layer normally. .pi/SYSTEM.md replaces the system prompt; APPEND_SYSTEM.md appends. Prompt templates in prompts/ become slash commands. → references/settings.md
• SDK — Programmatic embedding via createAgentSession(); createAgentSessionRuntime() for session replacement. → references/sdk.md
• Custom providers & models — models.json or extension pi.registerProvider() (config form or complete pi-ai providers) for any OpenAI-/Anthropic-/Google-compatible or custom LLM endpoint. → references/providers.md
• Sessions & compaction — Append-only JSONL with a tree structure; branch with /tree, /fork, /clone, compact with /compact. Auto-compaction triggers when contextTokens > contextWindow - reserveTokens. Extensions intercept via session_before_compact. → references/extensions.md and references/sdk.md

How to Use This Skill

For exact CLI flags run pi --help or read the relevant reference. Resource flags (--no-extensions, --no-skills, --no-context-files, --no-builtin-tools, etc.) are documented in references/settings.md.