Claude Code ships with 66+ built-in tools, a four-stage context compression pipeline, three multi-agent collaboration modes, a dual-call skill system, and a persistent memory taxonomy. It is a maximalist engineering effort — the agent equivalent of a Swiss Army knife with a blowtorch attachment.
Pi goes the other direction. It gives you seven tools, a TypeScript extension API, and a philosophy that can be summarized in one sentence: "There are many agent harnesses, but this one is yours."
Built by Earendil Inc. (led by Mario Zechner, creator of libGDX, with Armin Ronacher, creator of Flask, as co-maintainer), Pi has accumulated 79k GitHub stars and 5,100+ commits as a monorepo of four packages. The entire system prompt plus tool definitions fit under 1,000 tokens. The core agent loop is 792 lines of TypeScript. It is licensed under MIT and installable with a single curl command or an npm global install.
This article is a deep dive into Pi's architecture — what it includes, what it deliberately excludes, and why radical minimalism might be the right design choice for a coding agent in 2026.
引言
Claude Code 配备 66+ 内置工具、四阶段上下文压缩管道、三种多智能体协作模式、双重调用技能系统和持久记忆分类法。它是一个极致的工程——智能体版的瑞士军刀加喷火器。
Pi 走了相反的方向。它给你七个工具、一个 TypeScript 扩展 API，以及一句话哲学："Agent 有很多种，但这是你的。"
Pi 由 Earendil Inc. 开发（由 libGDX 作者 Mario Zechner 领导，Flask 作者 Armin Ronacher 共同维护），已在 GitHub 积累 79k 星和 5100+ 次提交。整个系统提示加工具定义不到 1,000 token。核心 Agent 循环仅 792 行 TypeScript。
本文将深入解析 Pi 的架构——它包含什么、刻意不包含什么，以及为什么激进极简主义可能是 2026 年编码智能体的正确设计选择。
The Anti-Feature Manifesto
Most coding agents compete on feature lists. More tools, more integrations, more automation, more guardrails. Pi's README reads like an anti-feature manifesto — a list of things it explicitly does not do:
| What Pi Omits | The Rationale |
|---|---|
| No MCP | Build CLI tools with READMEs, or add MCP via an extension |
| No sub-agents | Spawn more Pi instances via tmux, or build your own orchestration |
| No permission popups | Run in a container, or build a custom confirmation flow |
| No plan mode | Write plans to files, or implement planning via extensions |
| No built-in to-dos | Use a TODO.md, or extend the TUI |
| No background bash | Use tmux for full observability |
This is not laziness or incomplete engineering. Each omission is a deliberate architectural bet: features baked into a core become constraints; features implemented as extensions become choices.
Mario Zechner laid out the reasoning in two blog posts: "What I learned building an opinionated and minimal coding agent" (November 2025) and "What if you don't need MCP?" (November 2025). The MCP argument is particularly concrete. When you connect an MCP server to a coding agent, its entire tool description is dumped into the context every session — whether or not those tools are used. The Playwright MCP server costs 13,700 tokens (6.8% of a 200K context). Chrome DevTools MCP costs 18,000 tokens (9%). Pi's alternative: CLI tools with README files, invoked on-demand via the bash tool. The token cost is only paid when the tool is actually needed — progressive disclosure rather than upfront loading.
The sub-agent argument is equally pointed. Claude Code's sub-agents are described as "a black box within a black box" — the orchestrating instance spawns children with limited context transfer and poor observability. Pi's approach: spawn itself via bash (pi -p), giving the parent full visibility into the child's output as a regular tool result.
The to-do list argument is simpler: to-do lists "confuse models more than they help." Write a TODO.md file with checkboxes instead — the model can read it, update it, and it persists across sessions without any framework support.
When a coding agent ships with a built-in permission system, every user inherits that system's assumptions about what is safe. Pi's stance is more radical — what Mario calls "YOLO by default." Once an agent can read/write code and execute it, data exfiltration is nearly impossible to prevent without cutting network access entirely. Permission popups create a false sense of security. Pi's answer: if you need sandboxing, run the whole agent in a container. The Gondolin extension, Docker, or OpenShell all provide real isolation — unlike permission prompts that users learn to click through.
The bet is that a coding agent's core should be as small as possible, because every line of core code is a line every user must accept. Extensions are opt-in; core is not.
反特性宣言
大多数编码智能体在功能列表上竞争。更多工具、更多集成、更多自动化、更多护栏。Pi 的 README 读起来像一份反特性宣言——一份它明确不做的事情清单。
这不是懒惰或工程不完整。每个省略都是一个刻意的架构赌注：烘焙进核心的功能成为约束；作为扩展实现的功能成为选择。
Mario Zechner 在 two 篇博客中阐述了理由："What I learned building an opinionated and minimal coding agent" 和 "What if you don't need MCP?"（均为 2025 年 11 月）。MCP 论点特别具体：连接 MCP 服务器时，其整个工具描述每次会话都被注入上下文——无论这些工具是否被使用。Playwright MCP 服务器消耗 13,700 token（200K 上下文的 6.8%），Chrome DevTools MCP 消耗 18,000 token（9%）。Pi 的替代方案：带 README 的 CLI 工具，通过 bash 按需调用。
子智能体论点同样尖锐：Claude Code 的子智能体被描述为"黑箱中的黑箱"——编排实例生成上下文转移有限且可观察性差的子实例。Pi 的方法：通过 bash（pi -p）生成自己，让父实例对子实例的输出有完全可见性。
权限论点更激进——Mario 称之为"默认 YOLO"。一旦智能体能读写代码并执行，不切断网络访问就几乎不可能防止数据泄露。权限弹窗制造虚假的安全感。Pi 的回答：如果需要沙箱，在容器中运行整个智能体。
核心应该尽可能小，因为核心的每一行代码都是每个用户必须接受的。扩展是可选的；核心不是。
Seven Tools, Not Sixty-Six
Where Claude Code provides 66+ tools across six categories, Pi ships with four default tools and three optional ones:
Default Tools (always active)
| Tool | Description |
|---|---|
read | Read file contents (text + images), with offset/limit support |
write | Create or overwrite files, auto-creates parent directories |
edit | Edit files with exact text match replacement |
bash | Execute shell commands with stdout/stderr capture and optional timeout |
Optional Tools (disabled by default)
| Tool | Description |
|---|---|
grep | Search file contents with regex |
find | Find files and directories by pattern |
ls | List directory contents |
That is the complete action surface — seven tools at most, four by default. No web search, no web fetch, no sub-agent spawning, no task management, no plan mode toggling. Just filesystem operations and shell execution.
The rationale is straightforward: these seven tools cover the irreducible minimum for "read the codebase, make changes, and verify them." Everything else — web search, MCP servers, browser automation, LSP integration, image generation — can be added via extensions. The core provides the loop; extensions provide the vocabulary.
Tools can also be selectively disabled via --exclude-tools or restricted via --tools, giving users fine-grained control over what the agent can do in a given session. The --no-builtin-tools flag strips everything, leaving only extension-registered tools — useful for building domain-specific agents that should never touch the filesystem.
七个工具，而非六十六个
Claude Code 在六个类别中提供 66+ 工具，Pi 只配备四个默认工具和三个可选工具。默认工具：read（读取文件内容，支持文本和图片）、write（创建或覆盖文件）、edit（精确文本匹配替换）、bash（执行 shell 命令）。可选工具：grep（正则搜索）、find（按模式查找文件）、ls（列出目录）。
这就是完整的行动表面——最多七个工具，默认只有四个。没有网络搜索、没有子智能体生成、没有任务管理。只有文件系统操作和 shell 执行。
理由很直接：这七个工具覆盖了"阅读代码库、做修改、验证结果"的不可约最低要求。其他一切——网络搜索、MCP 服务器、浏览器自动化、LSP 集成——都可以通过扩展添加。核心提供循环；扩展提供词汇表。
工具还可以通过 --exclude-tools 选择性禁用或通过 --tools 限制，让用户对智能体在特定会话中能做什么有精细控制。--no-builtin-tools 标志剥离一切，只留下扩展注册的工具——适合构建永远不应接触文件系统的领域特定智能体。
The Agent Loop — Deliberately Compact
Claude Code's agent loop is a complex async generator with a four-stage compression pipeline (tool result budget → history snip → microcompact → context collapse), streaming parallel tool execution, memory prefetch, and concurrency-aware tool scheduling. It is engineered for long autonomous sessions where context management is the primary bottleneck.
Pi's agent loop takes a different approach. The core runtime lives in the @earendil-works/pi-agent-core package and is deliberately compact — exactly 792 lines for agent-loop.ts. Rather than building elaborate context management into the loop, Pi delegates compaction to extensions.
The loop itself follows the standard pattern:
1user message → build context → call model → parse response
2 → if tool calls: execute tools → append results → loop
3 → if text response: return to userWhere it gets interesting is in what the loop does not do:
- No built-in compression pipeline. Context overflow triggers compaction, but the compaction strategy is pluggable via extensions. You can implement summarization, truncation, selective history, or even an external RAG system. Default settings reserve 16,384 tokens for compaction overhead and keep the most recent 20,000 tokens of conversation.
- Parallel tool execution by default. Unlike what you might expect from a minimalist agent, Pi executes multiple tool calls in parallel. A file mutation queue prevents race conditions on parallel writes. Individual tools can opt into sequential execution via
executionMode: "sequential". - No memory prefetch. There is no persistent memory system in core. Long-term memory is an extension concern.
- No concurrency classification. Tools are not pre-categorized as concurrent-safe or exclusive. The loop executes them in parallel by default and relies on the file mutation queue for write safety.
This keeps the core loop auditable — a developer can read and understand the entire agent loop in an afternoon. Compare that with Claude Code's StreamingToolExecutor alone, which is 531 lines of concurrency management.
Context Engineering Without a Compression Pipeline
Pi's approach to context management is architectural rather than algorithmic. Instead of compressing messages after they accumulate, Pi controls what enters context in the first place:
- AGENTS.md: Project instructions loaded from
~/.pi/agent/, parent directories, and the current working directory. Pi walks up the directory tree and concatenates all matches. - SYSTEM.md: Replace the default system prompt entirely via
.pi/SYSTEM.md, or append to it viaAPPEND_SYSTEM.md. - Skills: On-demand capabilities loaded only when invoked, following the Agent Skills standard.
- Prompt templates: Markdown files with
{{variable}}placeholders, invoked via slash commands. - Dynamic context injection: Extensions can inject messages, filter history, implement RAG, or build long-term memory — all without modifying the core loop.
The compaction that does exist is "lossy by design" — older messages are summarized when context overflows, but the full history remains in the JSONL session file. This is a fundamentally different trade-off from Claude Code's approach: Pi accepts that the model may lose detail from early in a long session, in exchange for keeping the core loop simple. The full transcript is always recoverable from disk.
Agent 循环——刻意紧凑
Claude Code 的 Agent 循环是一个复杂的异步生成器，具有四阶段压缩管道、流式并行工具执行、记忆预取和并发感知调度。它为长自主会话而设计，上下文管理是主要瓶颈。
Pi 的 Agent 循环采取不同方法。核心运行时在 @earendil-works/pi-agent-core 包中，刻意紧凑——精确 792 行 agent-loop.ts。它将上下文压缩委托给扩展而非内建到循环中。
循环本身遵循标准模式：用户消息 → 构建上下文 → 调用模型 → 解析响应 → 如有工具调用则执行并循环 → 如有文本响应则返回用户。
有趣之处在于循环不做什么：
- 没有内置压缩管道 — 上下文溢出触发压缩，但压缩策略可通过扩展插拔。默认设置保留 16,384 token 的压缩开销和最近 20,000 token 的对话
- 工具默认并行执行 — 与极简智能体的预期不同，Pi 默认并行执行多个工具调用。文件变更队列防止并行写入的竞争条件
- 没有记忆预取 — 核心中没有持久记忆系统
- 没有并发分类 — 工具不被预先分类为并发安全或互斥，依赖文件变更队列保证写入安全
这使核心循环可审计——开发者一个下午就能阅读理解整个 Agent 循环。
没有压缩管道的上下文工程
Pi 的上下文管理方法是架构性的而非算法性的。它控制什么进入上下文而非在消息积累后压缩：
- AGENTS.md：从多个目录层级加载的项目指令
- SYSTEM.md：完全替换或追加默认系统提示
- 技能：按需加载的能力
- 动态上下文注入：扩展可注入消息、过滤历史、实现 RAG 或构建长期记忆
存在的压缩是"设计上有损的"——旧消息在上下文溢出时被总结，但完整历史保留在 JSONL 会话文件中。
The Extension System — Primitives, Not Features
Pi's extension system is where the real power lives. Extensions are TypeScript modules that receive an ExtensionAPI object and can register:
- Custom tools — add new actions the model can invoke
- Commands — slash commands for the user
- Keyboard shortcuts — custom keybindings
- Event handlers — react to session lifecycle events
- TUI components — custom terminal UI elements (status bars, overlays, headers, footers)
The extension API is deliberately broad. An extension can:
- Register a tool that spawns a sub-agent (giving Pi multi-agent capabilities)
- Register a tool that calls an MCP server (giving Pi MCP support)
- Register event handlers that implement plan mode (giving Pi planning capabilities)
- Register keyboard shortcuts that trigger git checkpoints (giving Pi version control integration)
- Replace the default compaction logic with a custom summarization strategy
- Add a custom editor for specific file types
- Build an entirely new UI overlay
Extensions hook into 25+ lifecycle events covering session management, agent loop phases, provider request/response interception, tool call blocking and modification, and user input transformation. Key events include before_agent_start (can modify the system prompt), tool_call (can block or modify tool invocations), tool_result (can transform results), and session_before_compact (can customize compression behavior).
This is what the Obsidian notes mean by "super versatile." Pi's core is a minimal loop, but the extension API makes it a framework for building your own coding agent. The 50+ extension examples shipping in the repo cover sandboxing, SSH execution, MCP integration, custom editors, status bars, overlays, and more.
Self-Modification
One particularly interesting capability: Pi can modify its own extensions in place and reload via /reload. This means the agent can evolve its own tooling during a session — writing a new extension, testing it, and continuing to use it without restarting. It is a form of self-improvement that operates at the extension layer rather than the core layer.
Extension Discovery
Extensions are discovered from three locations:
~/.pi/agent/extensions/— user-global extensions.pi/extensions/— project-local extensions- Pi Packages — installable bundles (more on this below)
The default export of an extension module may be async — Pi waits for async factories before continuing startup, which supports one-time initialization like fetching remote model lists or establishing WebSocket connections.
扩展系统——原语，而非功能
Pi 的扩展系统是真正的力量所在。扩展是接收 ExtensionAPI 对象的 TypeScript 模块，可以注册：自定义工具、命令、快捷键、事件处理器和 TUI 组件。
扩展 API 刻意宽泛。一个扩展可以：
- 注册一个生成子智能体的工具（给 Pi 多智能体能力）
- 注册一个调用 MCP 服务器的工具（给 Pi MCP 支持）
- 注册实现计划模式的事件处理器（给 Pi 规划能力）
- 替换默认压缩逻辑为自定义总结策略
- 构建全新的 UI 叠加层
这就是"超级通用"的含义。Pi 的核心是一个最小循环，但扩展 API 使其成为构建你自己编码智能体的框架。仓库中附带的 50+ 扩展示例涵盖沙箱、SSH 执行、MCP 集成、自定义编辑器等。
自修改
一个特别有趣的能力：Pi 可以就地修改自己的扩展并通过 /reload 重新加载。这意味着智能体可以在会话中进化自己的工具——编写新扩展、测试它、继续使用而无需重启。
Pi Packages — npm for Agent Capabilities
Pi extends the package management paradigm to agent capabilities. A Pi Package is a bundle that can contain extensions, skills, prompt templates, and themes. Packages are distributed via npm or git:
1# Install from npm
2$ pi install npm:@foo/pi-tools
3
4# Install from git
5$ pi install git:github.com/badlogic/pi-doom
6
7# Project-local install
8$ pi install npm:@foo/pi-tools -lA pi key in package.json declares resource paths; without it, Pi auto-discovers from conventional directory names. Packages install to ~/.pi/agent/npm/ or ~/.pi/agent/git/ for global scope, or project-local with -l.
This is reminiscent of how the Obsidian notes describe it: "no skills but they use npm + TypeScript to manage package." The comparison to a package manager is apt — Pi treats agent capabilities the same way developers treat code dependencies. You don't bake every library into your runtime; you install the ones you need.
Someone has already built pi-doom — a DOOM extension that runs inside Pi's TUI. If that doesn't demonstrate the extensibility of the system, nothing will.
The ecosystem extends well beyond the core repo. Mario maintains pi-skills (2,200+ stars), a curated skills collection covering browser tools, Google Calendar/Drive/Gmail CLIs, transcription, and VS Code integration — and notably, its skill format is cross-compatible with Claude Code, Codex CLI, Amp, and Droid, making it a de facto cross-agent standard. Other community packages include pi-diff-review (305 stars, a native diff review window with Monaco editor), pi-telegram (266 stars, a Telegram DM bridge for Pi sessions), and pi-share-hf (241 stars, a session publishing pipeline that redacts secrets and uploads traces to Hugging Face datasets).
Pi 包——智能体能力的 npm
Pi 将包管理范式扩展到智能体能力。Pi 包是可以包含扩展、技能、提示模板和主题的捆绑包，通过 npm 或 git 分发。
package.json 中的 pi 键声明资源路径；没有它，Pi 从约定目录名自动发现。
这让人想起 Obsidian 笔记中的描述："没有技能系统，但他们用 npm + TypeScript 管理包。"与包管理器的类比是恰当的——Pi 对待智能体能力的方式和开发者对待代码依赖的方式相同。你不会把每个库都烘焙进运行时；你安装你需要的那些。
已经有人构建了 pi-doom——一个在 Pi 的 TUI 中运行 DOOM 的扩展。如果这还不能展示系统的可扩展性，那没什么能了。
Tree-Structured Sessions — Branching Conversations
One of Pi's most distinctive features is its session model. Most coding agents store conversation history as a linear log — a sequence of messages from start to finish. Pi stores sessions as trees.
Each entry in the JSONL session file carries an id and parentId, forming a tree structure within a single file. This enables:
- Branching: The
/treecommand navigates session history in-place. You can return to any prior point and branch off in a new direction. - Forking:
/forkand/clonecreate new session files from prior points, giving you independent branches. - Selective export:
/exportrenders sessions as HTML;/shareuploads to a GitHub gist.
This is not a gimmick. Consider a real coding session: you start implementing feature A, realize halfway through that the architecture needs to change, and want to explore two different approaches. In a linear agent, you either start over or accept a polluted context. In Pi, you branch — explore approach 1 on one branch, approach 2 on another, and compare results. The full history of both explorations is preserved.
The tree model also enables a practice the Pi community encourages: publishing coding sessions to Hugging Face as datasets of real-world tasks, tool use, failures, and fixes. Tree-structured sessions capture not just the successful path but the decision points and abandoned approaches — richer training data than linear transcripts.
树结构会话——分支对话
Pi 最独特的特性之一是其会话模型。大多数编码智能体将会话历史存储为线性日志。Pi 将会话存储为树。
JSONL 会话文件中的每个条目都携带 id 和 parentId，在单个文件中形成树结构。这使得：
- 分支：
/tree命令就地导航会话历史，可以返回任何先前点并向新方向分支 - 分叉：
/fork和/clone从先前点创建新的会话文件 - 选择性导出：
/export渲染为 HTML；/share上传到 GitHub gist
这不是噱头。考虑一个真实的编码会话：你开始实现功能 A，中途意识到架构需要改变，想探索两种不同的方法。在线性智能体中，你要么重新开始，要么接受被污染的上下文。在 Pi 中，你分支——在一个分支上探索方法 1，在另一个上探索方法 2，然后比较结果。
树模型还支持 Pi 社区鼓励的实践：将会话发布到 Hugging Face 作为真实世界任务、工具使用、失败和修复的数据集。树结构会话不仅捕获成功路径，还捕获决策点和放弃的方法——比线性转录更丰富的训练数据。
Recursive Spawning — pi -p
Pi's print mode (pi -p "query") is a deceptively simple feature with powerful implications. It runs Pi non-interactively: takes a query, executes the agent loop, prints the result, and exits.
This means Pi can invoke Pi. A Pi session can use the bash tool to run pi -p "analyze this module" — spawning a child Pi instance with a focused task. The child runs to completion and returns its output as a tool result.
1Parent Pi: "Refactor the auth module"
2 |
3 +-- bash: pi -p "Read auth/ and list all exported functions"
4 | returns: "export: login(), logout(), refreshToken(), validateToken()"
5 |
6 +-- bash: pi -p "Check if any callers use refreshToken() directly"
7 | returns: "3 files call refreshToken() directly: api.ts, middleware.ts, test.ts"
8 |
9 Parent: decides on refactoring strategy based on child resultsThis is Pi's answer to multi-agent orchestration. Instead of building sub-agents into the core (as Claude Code does with AgentTool), Pi makes spawning new instances a natural consequence of having a CLI interface. The orchestration logic lives in the model's decision-making, not in framework code.
The Obsidian notes captured this well: "your coding agent can invoke pi very easily with pi -p to spawn more pi's — so great fit for building your own agent workflow."
This also makes Pi an excellent building block for external orchestration systems. Any script, CI pipeline, or other agent framework can invoke Pi as a subprocess with a natural language query and get back a result — no SDK integration required.
递归生成——pi -p
Pi 的打印模式（pi -p "query"）是一个看似简单但含义深远的特性。它以非交互方式运行 Pi：接受查询、执行 Agent 循环、打印结果、退出。
这意味着 Pi 可以调用 Pi。一个 Pi 会话可以使用 bash 工具运行 pi -p "分析这个模块"——生成一个专注任务的子 Pi 实例。子实例运行完成后将输出作为工具结果返回。
这是 Pi 对多智能体编排的回答。不是将子智能体内建到核心中（如 Claude Code 的 AgentTool），而是让生成新实例成为拥有 CLI 接口的自然结果。编排逻辑存在于模型的决策中，而非框架代码中。
这也使 Pi 成为外部编排系统的优秀构建模块。任何脚本、CI 管道或其他智能体框架都可以用自然语言查询将 Pi 作为子进程调用并获得结果——无需 SDK 集成。
Four Packages, One Architecture
Pi's codebase is organized as a TypeScript monorepo with four packages, each with a clear responsibility:
| Package | Role |
|---|---|
@earendil-works/pi-ai | Unified multi-provider LLM API — abstracts OpenAI, Anthropic, Google, and others behind a common interface |
@earendil-works/pi-agent-core | Agent runtime — tool calling, state management, the ~700-line agent loop |
@earendil-works/pi-coding-agent | The user-facing CLI — interactive TUI, file tools, bash tool |
@earendil-works/pi-tui | Terminal UI library — differential rendering for efficient terminal updates |
The layering is clean and bottom-up:
1pi-tui → terminal rendering
2pi-ai → model abstraction
3pi-agent-core → agent loop + tool calling
4pi-coding-agent → user-facing CLIA separate repo, earendil-works/pi-chat, handles Slack/chat automation and workflows — keeping the core repo focused on the terminal coding agent.
15+ Model Providers
Unlike Claude Code, which is tied to Anthropic's models, Pi supports a wide range of providers:
- Subscriptions: Anthropic Claude Pro/Max, OpenAI ChatGPT Plus/Pro, GitHub Copilot
- API keys: Anthropic, OpenAI, Google, Azure, Bedrock, Mistral, Groq, Cerebras, xAI, Hugging Face, Kimi, MiniMax, NVIDIA, OpenRouter, Ollama, and more
- Local models: llama.cpp router server
Models can be switched mid-session with /model or Ctrl+L, and favorites can be cycled with Ctrl+P. Custom providers speaking OpenAI, Anthropic, or Google APIs can be added via ~/.pi/agent/models.json.
四个包，一个架构
Pi 的代码库组织为 TypeScript monorepo，四个包各有明确职责：
pi-ai：统一多提供商 LLM APIpi-agent-core：Agent 运行时——工具调用、状态管理、约 700 行 Agent 循环pi-coding-agent：面向用户的 CLIpi-tui：终端 UI 库——差分渲染
分层干净且自底向上：pi-tui（终端渲染）→ pi-ai（模型抽象）→ pi-agent-core（Agent 循环 + 工具调用）→ pi-coding-agent（面向用户的 CLI）。
15+ 模型提供商
与绑定 Anthropic 模型的 Claude Code 不同，Pi 支持广泛的提供商：订阅（Anthropic Claude Pro/Max、OpenAI ChatGPT Plus/Pro、GitHub Copilot）、API 密钥（Anthropic、OpenAI、Google、Azure 等 15+ 家）和本地模型（llama.cpp）。模型可在会话中通过 /model 或 Ctrl+L 切换。
Security — Trust But Verify (Or Don't)
Pi's approach to security is as opinionated as everything else. The core ships with no built-in permission system for filesystem, process, network, or credential boundaries. Pi inherits the launching user's permissions.
Instead, Pi provides a project trust system and documents three containment patterns:
- Gondolin extension — keeps Pi and provider auth on the host machine; routes built-in tools and
!commands into a local Linux micro-VM. The model runs with full context on the host, but its actions are sandboxed. - Plain Docker — runs the entire Pi process in a local container. Simple but loses direct filesystem access.
- OpenShell — runs in a policy-controlled sandbox with fine-grained permission rules.
On startup, Pi prompts before trusting project folders containing local settings or resources. Before a trust decision, only context files, user/global extensions, and CLI-specified extensions load. Non-interactive modes rely on defaultProjectTrust from global settings (ask, always, or never).
This "no permissions by default, bring your own sandbox" approach is polarizing. For experienced developers working in controlled environments, it eliminates the friction of permission popups that plague other agents. For teams needing strict audit trails and approval gates, it requires upfront investment in containerization or custom permission extensions.
安全——信任但验证（或不验证）
Pi 对安全的方法和其他一切一样有主见。核心不内置权限系统——Pi 继承启动用户的权限。
相反，Pi 提供项目信任系统并记录三种容器化模式：Gondolin 扩展（将工具路由到本地 Linux 微虚拟机）、纯 Docker（在容器中运行整个进程）、OpenShell（策略控制的沙箱）。
这种"默认无权限，自带沙箱"的方法是有争议的。对于在受控环境中工作的经验丰富的开发者，它消除了困扰其他智能体的权限弹窗摩擦。对于需要严格审计轨迹和审批门的团队，它需要在容器化或自定义权限扩展上进行前期投入。
Supply Chain Hardening
A detail worth noting: Pi takes dependency security seriously, which is unusual for an open-source project of its kind.
- Direct external dependencies are pinned to exact versions
.npmrcenforcessave-exact=trueandmin-release-age=2to avoid same-day dependency releasespackage-lock.jsonis the ground truth; pre-commit blocks accidental lockfile commits unless an explicit environment variable is set- A generated shrinkwrap pins transitive dependencies for the published CLI package
- Release smoke tests build, pack, and install in isolated npm and Bun environments before tagging
- CI runs
npm audit --omit=devplus signature verification on a scheduled basis
In an era where coding agents have access to your filesystem, shell, and API keys, supply chain attacks through compromised dependencies are a real threat. Pi's hardening measures are a welcome departure from the typical "just npm install" approach.
供应链加固
值得注意的细节：Pi 认真对待依赖安全——这在其类型的开源项目中并不常见。
直接外部依赖固定到精确版本；min-release-age=2 避免同日依赖发布；package-lock.json 是唯一事实来源；生成的 shrinkwrap 固定已发布 CLI 包的传递依赖；发布冒烟测试在隔离环境中构建、打包和安装。
在编码智能体可以访问你的文件系统、shell 和 API 密钥的时代，通过被入侵依赖的供应链攻击是真实威胁。Pi 的加固措施是对典型的"只需 npm install"方法的受欢迎的背离。
15+ Providers, 4 APIs
Despite supporting over 15 model providers, Pi's provider abstraction is simpler than it appears. Beneath the surface, there are really only four APIs:
- OpenAI Completions — used by OpenAI, Azure, Groq, Cerebras, xAI, and others
- OpenAI Responses — OpenAI's newer response-based API
- Anthropic Messages — used by Anthropic and AWS Bedrock
- Google Generative AI — used by Google and Google Vertex
The remaining complexity is in handling provider quirks: Cerebras and Mistral reject the store field, Mistral uses max_tokens instead of max_completion_tokens, several providers don't support the developer role, and xAI rejects reasoning_effort. Pi's @earendil-works/pi-ai package abstracts all of this behind a unified interface.
Cross-provider context handoff was designed from the start. When switching from Anthropic to another provider mid-session, Anthropic's thinking traces are converted to content blocks with <thinking> tags. Provider-specific signed blobs are replayed on subsequent requests to maintain cache efficiency.
15+ 提供商，4 个 API
尽管支持超过 15 个模型提供商，Pi 的提供商抽象比表面看起来更简单。底层实际只有四个 API：OpenAI Completions、OpenAI Responses、Anthropic Messages 和 Google Generative AI。其余复杂性在于处理各提供商的怪癖。
跨提供商上下文交接从一开始就被设计。从 Anthropic 切换到其他提供商时，Anthropic 的思考轨迹被转换为带有 <thinking> 标签的内容块。
Evidence That Minimalism Works
The philosophical argument for minimalism is compelling, but does it actually perform? Pi ran Terminal-Bench 2.0 — a standardized benchmark for terminal-based coding agents — with Claude Opus 4.5 across five trials per task. Results were competitive against Codex, Cursor, and Windsurf.
The most telling data point comes from Terminal-Bench's own Terminus 2 agent — a minimal baseline that gives the model nothing but a tmux session and basic file tools. No fancy context compression, no parallel execution, no multi-agent coordination. Terminus 2 holds its own against far more sophisticated agents, suggesting that frontier models have become capable enough that the agent harness matters less than we think. As Mario puts it: "Frontier models have been heavily RL-trained and inherently understand what a coding agent is."
This is the strongest argument for Pi's design philosophy. If a bare tmux session with basic tools performs competitively with agents that have 66+ tools and four-stage compression pipelines, then perhaps the value of a coding agent lies not in its features but in its ergonomics — how comfortably it lets the developer interact with the model.
极简主义有效的证据
哲学论点是令人信服的，但实际表现如何？Pi 用 Claude Opus 4.5 在 Terminal-Bench 2.0（终端编码智能体标准化基准）上运行，每个任务五次试验，结果与 Codex、Cursor 和 Windsurf 具有竞争力。
最有说服力的数据来自 Terminal-Bench 自己的 Terminus 2 智能体——一个只给模型一个 tmux 会话和基本文件工具的最小基线。没有花哨的上下文压缩、没有并行执行、没有多智能体协调。Terminus 2 与远比它复杂的智能体保持竞争力，表明前沿模型已经足够强大，智能体框架的重要性比我们想象的小。正如 Mario 所说："前沿模型经过了大量 RL 训练，本质上理解编码智能体是什么。"
如果带有基本工具的裸 tmux 会话与拥有 66+ 工具和四阶段压缩管道的智能体竞争力相当，那么编码智能体的价值也许不在于其功能而在于其人体工程学。
Pi vs. Claude Code — A Design Philosophy Comparison
| Dimension | Claude Code | Pi |
|---|---|---|
| Philosophy | Batteries included — comprehensive out-of-the-box | Primitives, not features — build your own |
| Built-in tools | 66+ across 6 categories | 4 default + 3 optional (read, write, edit, bash, grep, find, ls) |
| Agent loop | ~thousands of lines with 4-stage compression | 792 lines, compression delegated to extensions |
| System prompt | Large, with detailed instructions | Under 1,000 tokens total (prompt + tool definitions) |
| Tool execution | Streaming parallel with concurrency classification | Parallel by default with file mutation queue |
| Memory | Four-type taxonomy with semantic recall | None in core, extensions can implement |
| Multi-agent | Three built-in modes (sub-agent, orchestrator, swarm) | Recursive pi -p spawning or extension-based |
| Skills | Dual-call (user + model), lazy loaded | Agent Skills standard, on-demand loading |
| Permissions | Built-in permission system with popups | None in core; containerization or extensions |
| Model support | Anthropic models only | 15+ providers (4 underlying APIs) including local models |
| Session model | Linear with compression | Tree-structured with branching |
| Extensions | MCP + skills + hooks | TypeScript extension API + 25+ events + Pi Packages |
| License | Apache 2.0 | MIT |
These are not better-or-worse comparisons. They represent two valid answers to the question "what should a coding agent be?"
Claude Code's answer: a comprehensive, opinionated system that handles the complexity of autonomous coding sessions so the user doesn't have to think about it. The four-stage compression pipeline, streaming tool execution, and multi-agent coordination are all invisible infrastructure — the user just describes what they want done.
Pi's answer: a minimal, extensible framework that gives the user (or the user's organization) full control over what the agent is and does. The seven tools handle the basics; everything else is shaped by the extensions the user chooses to install or build.
Pi vs. Claude Code——设计哲学对比
| 维度 | Claude Code | Pi |
|---|---|---|
| 哲学 | 电池全含——开箱即用的全面性 | 原语而非功能——构建你自己的 |
| 内置工具 | 66+ | 4 默认 + 3 可选 |
| Agent 循环 | 数千行 + 四阶段压缩 | 792 行，压缩委托给扩展 |
| 系统提示 | 大型，含详细指令 | 总共不到 1,000 token |
| 工具执行 | 流式并行 + 并发分类 | 默认并行 + 文件变更队列 |
| 记忆 | 四类分类法 + 语义召回 | 核心无，扩展可实现 |
| 多智能体 | 三种内置模式 | 递归 pi -p 或基于扩展 |
| 模型支持 | 仅 Anthropic | 15+ 提供商（4 个底层 API） |
| 会话模型 | 线性 + 压缩 | 树结构 + 分支 |
| 扩展 | MCP + 技能 + hooks | TypeScript 扩展 API + 25+ 事件 + Pi 包 |
这不是好坏的比较。它们代表了对"编码智能体应该是什么"这个问题的两个有效回答。
Claude Code 的回答：一个全面、有主见的系统，处理自主编码会话的复杂性，用户无需思考。Pi 的回答：一个最小、可扩展的框架，给用户（或用户的组织）对智能体的完全控制。
Conclusion — The Case for Minimalism
Pi's 79k stars suggest a significant audience for its philosophy. In a landscape where coding agents are adding features faster than users can learn them, Pi makes a compelling counterargument: the best agent framework might be the one that does the least, but enables the most.
Its seven tools cover the irreducible minimum for coding work. Its extension API covers everything else. Its tree-structured sessions capture the non-linear reality of how developers actually work. Its model-agnostic design means it is not locked into any single provider's ecosystem. And its 792-line agent loop can be understood, audited, and modified by anyone who cares to look.
The Terminal-Bench 2.0 results add empirical weight to the philosophy: a minimal agent with basic tools performs competitively with feature-rich systems. The value of a coding agent may lie less in its feature count and more in its ergonomics and extensibility.
The Obsidian notes called Pi "a middle finger to Claude Code." That framing is provocative but captures something real. Where Claude Code says "we've thought of everything so you don't have to," Pi says "you know your workflow better than we do — here are the primitives, build what you need."
For developers who want a coding agent that works out of the box with minimal configuration, Claude Code's comprehensive approach is the right choice. For developers who want to build their own agent workflows, integrate coding agents into larger systems, or maintain full control over what their agent can and cannot do, Pi's minimalism is not a limitation — it is a feature.
总结——极简主义的理由
Pi 的 79k 星表明其哲学有广泛的受众。在编码智能体添加功能比用户学习速度更快的环境中，Pi 提出了一个令人信服的反论：最好的智能体框架可能是做得最少但赋能最多的那个。
它的七个工具覆盖了编码工作的不可约最低要求。它的扩展 API 覆盖其他一切。它的树结构会话捕获了开发者实际工作的非线性现实。它的模型无关设计意味着它不锁定在任何单一提供商的生态系统中。它约 700 行的 Agent 循环可以被任何愿意看的人理解、审计和修改。
Obsidian 笔记称 Pi 为"对 Claude Code 的竖中指"。这个说法挑衅但捕捉到了真实的东西。Claude Code 说"我们已经想到了一切所以你不需要"，Pi 说"你比我們更了解你的工作流——这是原语，构建你需要的"。
对于想要开箱即用的编码智能体的开发者，Claude Code 的全面方法是正确选择。对于想要构建自己的智能体工作流、将编码智能体集成到更大系统中、或保持完全控制的开发者，Pi 的极简主义不是限制——它是功能。