Pi is a minimal, open-source terminal coding harness (45.5K GitHub stars, 2.5M weekly NPM downloads) built on a "small core with programmable edges" philosophy. Unlike feature-heavy AI tools, Pi provides only five core actions—reading files, running bash, editing files, writing, and managing sessions—expecting users to adapt the tool to their workflows rather than vice versa.
🧠Core Philosophy & Setup
- Pi's core is deliberately bare, lacking built-in plan mode (available via extension for faster iterative coding).
- Everything else—models, agents.md, skills, prompts, extensions—is customizable.
- Install via a one-line shell command from pi.dev; works on Linux, Mac, or WSL (Windows Subsystem for Linux).
- Connect via subscriptions (Claude Pro Max, ChatGPT Plus/Pro, GitHub Copilot) or API keys (Anthropic, OpenAI, Grok, Mistral, xAI, Azure, Bedrock, OpenRouter).
- Use
/loginto authenticate;pi [prompt]runs commands directly, orpi --provider [provider] [model] [prompt]for specific models.
🧠Navigation & Key Commands
- Control L: Select model; Control P: Cycle models; Shift+Tab: Adjust thinking level.
- Control G: Open external editor (e.g., VSCode) for composing prompts.
!! [command]: Run bash without sending output to LLM;! [command]: Run bash and send output to LLM.- Four modes: Interactive (full TUI), Print/JSON (for scripts), RPC (non-Node integration), SDK (embed Pi in apps like Open Claw).
- Bottom bar shows current folder, spending, context window percentage, model, thinking level, and active skills.
🌳 Sessions, Branching & Recovery
- Sessions are tree structures: branch from any earlier message using
/tree. - Fork: Create new path from a previous message (changes conversation history, not file state).
- Clone: Duplicate current session at its present point.
- Resume sessions with
pi -c(continue last) orpi -r(resume from list). Delete sessions with Control D. - No built-in file undo: Use Git or checkpoint extensions;
/undoonly affects prompts, not file changes.
🛠️ Extending Pi (Skills, Prompts, Extensions)
- System.md: Replace default system prompt; appendSystem.md: Add to it.
- agents.md (in
.pi/agent/): Project-specific behavior rules (e.g., project tree). - Skills (
.pi/agents/[skill]/): Reusable capability packages withskill.md(name, description, prompt). - Prompts (
.pi/prompts/): Saved templates expandable via/commands. - Extension layers: settings.json (defaults), agents.md (project rules), system.md (identity), prompts (repeat), skills (capability), extensions (behavior), packages (share).
- Explore packages at pi.dev/packages (e.g., context mode saving 98% context, web search, MCP plugins).
🔚 What Pi Leaves Out Pi omits built-in MCP, subagents, permission pop-ups, background bash, to-do lists, and plan mode. The core rule: if you need a workflow daily, make it a template, skill, extension, or package.
Final Takeaway: Pi empowers you to build a personalized, efficient agent by shaping only what you need—and nothing more. Its extensibility and minimalism make it ideal for developers who prefer control over preset features.