老实说，这是因为我已经受够了 Claude Code。我喜欢 Claude Code；这是一个定义了 Coding 的产品，团队也很优秀。但输出总是会出问题。
我说的不是 Bug；我的工作流会被打断，是因为 Harness 发生了变化，而模型的行为也随之改变。
作为一名工程师，我需要更可靠的工具。当然，在 2026 年说这句话有点讽刺，因为 LLM 本身就不可靠。不过，至少我可以让其中一部分变得确定性更强，而且我希望它们如此，包括工具、系统提示词，以及注入其中的一切内容。
如果你观察 Claude Code 或 OpenAI 的 Codex，就会发现它们会在 UI 中不显示的情况下，偷偷将大量内容塞进你的上下文。这些东西会以最隐蔽的方式干扰你的工作流。
它们每天发布一次，甚至一天发布多次。你可以在上午 9 点开始工作，工作流运行得非常完美；然后上午 10 点它突然失效，到了下午 3 点行为又完全不同了——模型没有改变，改变的只是 Harness。在这种情况下，我无法工作。
Claude Code、OpenCode 和 Codex：几乎每个月都会有新功能加入 Coding Agent。MCP、Subagents、Plan Mode、后台执行。可能性增加了，但也越来越难以追踪幕后究竟发生了什么。
pi 逆潮流而行。它在 GitHub 上已经获得了超过 99,000 颗星。它的创建者 Mario Zechner 是一位因 Java 游戏框架而闻名的工程师。他对现有的 Coding Agent 感到不满，于是从头开始为自己编写了一个。
其设计原则是：“如果我不需要它，就不会构建它。”现有工具会在幕后注入上下文，让用户无法看到正在发生什么。这正是他的动机。
开始之前！🦸🏻 ♀️
Pi 的极简设计受到了什么启发？
在 Mario 撰写关于 Pi 的文章之前，他查看了 Terminal Bench 排行榜，其中有一个名为 Terminus 的 Harness 相当出色。它只向 LLM 提供一个工具，用于与 tmux 会话交互。
LLM 必须发送单独的按键，并读取 tmux 返回的 ANSI 序列，才能完成任务。仅凭这一个工具，它几乎总能进入前三名，而且经常排名第一。
这给了我一个关键直觉：模型如今已经通过强化学习得到了大量训练，因此它们自然知道什么是 Coding Harness，不需要在此基础上添加太多内容。Pi 正是这一理念的体现：一个极简但可扩展的 Harness。
Pi Agent 的独特之处
Pi 的设计最引人注目的地方，是它有意省略了其他 Coding Agent 通常具备的功能。
并不是功能不够，而是我决定不添加它。
Zechner 在他的博客中质疑了 MCP。问题不在于协议本身，而在于 Token 成本。Playwright MCP 使用 21 个工具和 13,700 个 Token，占用上下文窗口的 7–9%。Chrome DevTools MCP 使用 26 个工具和 18,000 个 Token。
如果你连接到 MCP Server，每个会话中所有工具定义都会被灌入上下文。CLI 工具有 README。你只需要在必要时阅读并运行它们。没有理由持续消耗上下文。
Subagents 也是如此。Claude Code 会在内部启动 Subagents，只返回摘要后的结果。内部发生了什么，从外部无法看到。pi 使用 tmux 将多个实例并排显示。所有交互都可以由人直接读取。
现有 Harness 的另一个问题是，系统提示词和工具定义经常变化，用户无法控制哪些上下文被注入。pi 将系统提示词限制在 1,000 个 Token 以下，并完整公开其内容。
其一贯原则是，Harness 不应该规定工作流。如果缺少某项功能，用户应该自行创建。
OpenCode 和 Claude Code 中没有的功能
pi 采用了减法式设计，但它也具备 Claude Code 所缺少的功能。
在会话期间切换模型
pi 中的 Context 会以与 Provider 无关的格式进行序列化。即使你使用 Anthropic 开始工作，中途切换到 OpenAI，上下文也会保留。你可以使用 /model 或 Ctrl+L 立即切换。
我们也统一了处理思考的方式。Claude 的 Extended Thinking、OpenAI 的 Reasoning Effort，以及 Gemini 的 Thinking Budget，都会以从 minimal 到 xhigh 的五级尺度呈现。
JSONL Tree Session
会话历史以 JSONL 格式存储。每个条目都有一个 id 和一个 parentId，从而形成树结构。/tree 命令允许你返回过去的任意节点，并从那里扩展出另一条分支。
它类似于 Git Branch，但历史记录都保存在单个文件中。当你想回到之前采用的方案时，不需要从头重新开始会话。
PiPops
Extensions、Skills、Prompt Templates 和 Themes 可以通过 npm 或 git 一起分发。
pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi config # Enable or disable
该工具本身内置了供社区创建和分享 Extensions 的机制。
扩展机制
Pi 即使功能有限也能够使用，是因为它有三种扩展能力的方式。
Extensions 提供了最大的灵活性。你可以使用 TypeScript 编写它们，并添加自定义工具、命令、快捷键和事件处理器。你可以在工具调用前后插入 Hooks，例如，可以像下面这样编写一个阻止危险命令的 Extension。
import { ExtensionAPI } from "@mariozechner/pi-coding-agent";
export default function (pi: ExtensionAPI) {
pi.on("tool_call", async (event, ctx) => {
if (event.toolName === "bash"
&& event.input.command.includes("rm -rf")) {
const ok = await ctx.ui.confirm(
"Dangerous!", "Allow rm -rf?"
);
if (!ok) return { block: true, reason: "Blocked" };
}
});
}
我们并没有移除 Claude Code 的权限确认弹窗。我们只是让用户可以根据自己的标准创建代码。
Skills 是符合 Agent Skills 标准，并遵循与 Claude Code 中 Skills 相同规范的 SKILL.md 文件。
Prompt Templates 是可复用的 Markdown 文件，可以使用 /templatename 展开。也可以使用 Mustache 变量（{{variable}}）。
1. 基本安装
安装只需要一条命令。
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
另一种方法是使用安装脚本。
curl -fsSL https://pi.dev/install.sh | sh
有两种身份验证方式。
# Use an API key
export ANTHROPIC_API_KEY=sk-ant-...
pi
# Use an existing subscription
pi
/login # Select a provider
/login可以直接使用现有订阅，例如 Anthropic Claude Pro/Max、OpenAI ChatGPT Plus/Pro (Codex) 和 GitHub Copilot。
这段视频的重点是，学习曲线极低。 只需安装并与它交互，它就会开始工作。
2. 模型设置
这是视频中耗时最长的部分（大约 9 分钟）。Pi 支持超过 15 个不同的 LLM Provider。以下是其中一些主要 Provider：
- Anthropic
- OpenAI
- Google Gemini / Vertex
- DeepSeek
- xAI
- OpenRouter
- Amazon Bedrock
- Azure OpenAI
- Groq / Cerebras / Mistral など
在会话中途切换模型是完全正常的。
/model # Model selection screen
Ctrl+L # Same as above
Shift+Tab # Switch thinking level (off–max)
可以添加自定义 Provider ~/.pi/agent/models.json，如果它们使用 OpenAI/Anthropic/Google 兼容的 API，只需进行配置即可使用。你也可以连接到像 llama.cpp 这样的 Router Server，以使用本地模型。
Pi 极力强调的优势之一，就是它“不会锁定到某个 Provider”。
3. 会话管理
Pi 会话会保存为树结构的 JSONL 文件。保存位置是指定的，每条消息在 ~/.pi/agent/sessions/中都有单独的位置。idparentId
得益于这种结构，以下所有操作都可以在单个文件中完成：
pi -c # Continue the most recent session
pi -r # Select from previous sessions
以下是会话期间的主要命令。
/tree尤其有意思。你可以回到对话中的“任意位置”，并从那里分支继续编写。完整历史都保存在一个文件中，因此你可以立即意识到：“哦，我想按照 30 分钟前的方式继续。”
/compact会对旧消息进行总结并压缩上下文。 默认情况下也会启用自动压缩，如果发生上下文溢出，它会自动恢复并重试。
4. Plugin Extensions
真正的 Pi 就体现在这里，视频中大约花了 10 分钟介绍这一部分。Pi 的自定义由四个层次组成。
Extensions (TypeScript) → Tools, commands, UI, and event handling
Skills → Procedures/instructions written in Markdown
Prompt Templates → Reusable prompts
Themes → Display themes
pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi list
pi update --all
使用 Extensions，你可以完成以下所有操作：
添加自定义工具（包括替换内置工具）。
自定义创建 Sub-agents 和 Plan Mode
权限门控和路径保护
添加 Status Line、Header 和 Footer 等 UI 元素。
Git Checkpoint / 自动提交
MCP Server 集成
（甚至可以在等待时运行 Doom。）
这段视频的重点是，其他 Agent 内置在产品中的所有功能（Sub-agent、Plan Mode、权限弹窗），都可以使用 Extensions 创建。
因此，Pi 的设计理念是保持核心功能精简。
5. Skills
Skills 是以 Markdown 文件编写的“能力包”。 遵循 Agent Skills 标准，包含这些 Skills 的文件夹 SKILL.md构成一个 Skill。
<!-- ~/.pi/agent/skills/my-skill/SKILL.md -->
# My Skill
Use this skill when a user asks about X.
text ## Steps 1. Perform this action. 2. Then perform that action.
除了通过 `/skill:name`显式调用之外，如果任务匹配，Agent 也会自动加载它。
这里的重点是，**Skills 被设计为仅在需要时进入上下文**。它们不会被全部塞进系统提示词，而只会在使用时展开。这就是如何维持 1,000 Token 系统提示词的方式。
### 6. Pi Web（浏览器 UI）
视频还介绍了浏览器 UI“Pi Web”。
```css
npx @agegr/pi-web@latest以下是主要功能。
会话工作区：按项目列出、恢复、重命名和删除过去的对话。
两种分支路径：从某条消息创建新会话，或在当前会话中创建分支。
查看项目文件，显示 Git Diff。
切换 Git Worktree
通过 Web 配置 Provider 登录、模型、Package 和 Skill。
~/.pi/agent由于它与终端版本的 pi 共享相同的设置和会话文件，因此可以在浏览器和终端之间随时切换，非常方便。
7. 记忆系统
事实证明，整理与视频相关的“记忆”非常简单。
我们的立场是，Pi 不需要独立的长期记忆数据库。
1. The session itself is memory
The entire history is saved as JSONL and can be resumed at any time.
2. AGENTS.md / CLAUDE.md
Write project conventions, instructions, and commands in these files.
They are loaded at startup from global settings and the directory hierarchy.
3. Compaction
Long sessions are compressed by summarizing older parts.
However, the complete history remains in JSONL, so you can go back with /tree.
换句话说，职责划分如下：“我们已经做过什么”由会话处理，而“我们希望你记住什么”由 AGENTS.md 处理。
作为衍生功能，通过 Extension 添加记忆功能也是一种常见用例。
8. 安全使用
Pi 没有内置 Sandbox。Read/Write/Edit/Bash 操作会使用启动 Pi 的用户权限运行。Extensions 也是如此。
这是一个设计选择。一个不完善的进程内 Sandbox 只能提供“看似安全的边界”，因此官方的立场是将真正的隔离交给 OS 以及 Container/VM 层。
视频强调，必须始终在隔离环境中处理不受信任的 Repository 和无人值守执行。
# 1. Put the entire pi environment in Docker (simplest)
# 2. Run pi on the host and route only tool execution
# to a local micro-VM (Gondolin)
pi -e ~/.pi/agent/extensions/gondolin
还有一种名为 Project Trust 的机制。它是一种“输入读取防护”，用于防止 Repository 任意覆盖 pi 的设置或 Extensions；默认情况下，对于未经验证的项目，它会要求确认。
不过，需要注意的是，这并不能完全阻止 Prompt Injection。当你处理未指定的代码或文档时，使用这种方法仍需牢记这一点。
9. 创建自己的 Plugins
视频最后一部分（大约 5 分钟）是实现部分，内容是“编写自己的 Extension”。
最小的 Extension 只需要一个 TypeScript 文件。
export default function (pi: ExtensionAPI) {
pi.registerTool({
name: "deploy",
// Tool definition (input schema, execution logic)
});
pi.registerCommand("stats", {
// Custom command definition });
pi.on("tool_call", async (event, ctx) => {
// Intercept tool calls and process them
}); }
如果将这个文件放在 ~/.pi/agent/extensions/（面向整个用户组），或按项目放在 .pi/extensions/中，它就会在 Pi 启动时自动加载。若只是进行一次性测试，可以使用 pi -e ./my-ext.ts。
官方 Repository 包含许多自动提交、Git Checkpoint、MCP 集成和自定义压缩的示例。在 Pi 中，“所需功能没有内置”是理所当然的；标准做法是自行添加，或安装一个 Package。
我的看法：
我们可以从 Pi 中学到三点。
你添加的功能越多，用户看不见的处理过程就越多。Subagents、后台执行、自动压缩都很方便，但它们会增加黑盒的数量。pi 优先考虑让人类直接观察所有交互。
当你站在构建自己的 Agent 的角度时，pi 的设计决策就成为一个参考点。不要从一个包罗万象的 Package 开始，而应从四个工具和一个 1,000 Token 的系统提示词开始，只添加你需要的内容。设计的起点不是要添加什么，而是要移除什么。