Pi Coding Agent

My notes

Summary

Pi is a minimal, self-modifying terminal coding agent (harness) that ships with deliberately few baked-in features and lets you build the rest via TypeScript extensions, skills, and packages. Where most coding agents bundle sub-agents and plan mode by default, Pi makes you (or Pi itself) add them on demand. It’s a “context engineering” tool aimed at people who want full control over the context window and agent behaviour.

Key Insight

Inverted philosophy vs. Claude Code / Cursor

• Ships minimal on purpose: no sub-agents, no plan mode out of the box.
• You ask Pi to build the feature, or install a community package that adds it.
• 50+ example extensions exist: sub-agents, plan mode, permission gates, path protection, SSH execution, sandboxing, MCP integration.

Self-modifying loop

• Pi can rewrite its own code in place, then /reload and keep going in the same session.
• Extensions are TypeScript modules with access to tools, commands, keyboard shortcuts, events, and the full TUI.

Provider-agnostic

• Anthropic, OpenAI, Google, Azure, Bedrock, Mistral, Groq, Cerebras, xAI, Hugging Face, Kimi, MiniMax, OpenRouter, Ollama. API key or OAuth.
• Switch models mid-session (/model or Ctrl+L), cycle favourites with Ctrl+P.

Context engineering primitives

• AGENTS.md for project instructions (loaded from ~/.pi/agent/, parent dirs, cwd).
• SYSTEM.md to replace or append the system prompt per-project.
• Customizable compaction via extensions (topic-based, code-aware, alternate summarization model).
• Skills loaded on-demand with progressive disclosure that doesn’t bust the prompt cache.

Session model

• Sessions stored as trees; /tree navigates to any prior point and branches, all in one file.
• /export to HTML, /share uploads to a GitHub gist with a rendered shareable URL.

Four run modes: interactive TUI, print/JSON (pi -p "query", --mode json), RPC (JSON over stdin/stdout for non-Node), and SDK (embed in apps).