pi-cc-subagent

中文 | English

一个 pi extension，在 pi 里完整复刻 Claude Code 的 subagent 体系。

pi 官方立场是核心不内置 sub-agents（"It intentionally does not include built-in MCP, sub-agents, … You can build or install those workflows as extensions"），本 extension 就是那个 workflow。

功能对照 Claude Code

Claude Code	本 extension
Agent (Task) tool	agent 工具
内置 general-purpose agent	general-purpose（全工具）
内置 Explore agent	explore（只读搜索，返回结论不返回文件内容）
内置 Plan agent	plan（只读架构师，输出实施计划）
.claude/agents/*.md 自定义 agent	.pi/agents/*.md 与 ~/.pi/agent/agents/*.md，并直接兼容读取 .claude/agents/ 和 ~/.claude/agents/
依据 description 自动委派	agent 类型描述注入 agent 工具描述 + 系统提示 Guidelines
单条消息并行多个 agent	pi 默认并行执行同一条消息里的多个工具调用
后台运行 + 完成通知	run_in_background: true，完成后以 steer 消息通知并触发父 agent 响应
TaskOutput 轮询后台任务	agent_output 工具
SendMessage 继续已有 agent	resume: "<agentId>"（子会话落盘，凭 id 恢复上下文）
/agents 管理界面	/agents 命令（列表 + 详情，支持参数补全）
isolation: "worktree" 隔离	isolation: "worktree"：子 agent 在独立 git worktree（HEAD 的干净签出）里运行；无改动自动删除，有改动保留分支并在结果中报告 diff 与合并指引
子 agent 不能再派生子 agent	子进程以 --no-extensions 启动，天然没有 agent 工具
Esc 中断	父 agent abort 时 SIGTERM 子进程

安装

方式一：pi install（推荐）

pi install git:github.com/linearuncle/pi-cc-subagent

# 卸载
pi remove git:github.com/linearuncle/pi-cc-subagent

方式二：手动复制单文件

# 全局（所有项目可用）
cp subagent.ts ~/.pi/agent/extensions/

# 或项目级
mkdir -p .pi/extensions && cp subagent.ts .pi/extensions/

# 或临时试用
pi -e ./subagent.ts

无需 npm install，只依赖 pi 自带的包和 Node 内置模块。两种方式二选一，都装会重复注册工具。

实现原理

agent 工具通过子进程运行子 agent：

pi --mode json --no-extensions \
   --name "agent:<type>: <description>" \
   [--tools read,grep,find,ls,bash] \
   [--model <parent 模型或覆盖>] [--thinking <parent 思考等级>] \
   --append-system-prompt "<agent 角色设定 + subagent 协议>" \
   "<prompt>"

• --mode json：逐行 JSON 事件流，父进程实时解析，把"第几轮、正在跑哪个工具"渲染成 TUI 进度。
• --no-extensions：防止递归加载本 extension（= Claude Code 里子 agent 没有 Agent tool）。
• --tools：按 agent 定义限制工具（explore/plan 只读）。
• 会话落盘：子 agent 会话正常保存并命名为 agent:<type>: …，可用 pi -r 翻查完整过程， 也是 resume 的基础（--session <uuid> 恢复）。
• 模型/思考等级继承：默认继承父会话当前模型与 thinking level，可被 agent 定义或调用参数覆盖。
• 子 agent 最终回复经 50KB/2000 行截断后作为工具结果返回。

触发方式

1. 自动委派：模型根据 agent 工具描述里各 agent 类型的 description 自行决定 （description 里写 "Use PROACTIVELY" 等字样可提高触发率）。
2. 点名：直接说"用 explore agent 找一下 X"、"launch two agents in parallel to …"。
3. 并行：模型在一条消息里发多个 agent 调用，pi 并行执行。
4. 后台：要求后台运行时模型传 run_in_background: true，完成后自动通知。
5. 继续对话：结果尾部带 agentId，模型可用 resume 继续该 agent。
6. /agents：查看当前可用的 agent 类型及来源。

自定义 agent

在 .pi/agents/（项目）或 ~/.pi/agent/agents/（全局）放 markdown 文件； 已有的 .claude/agents/、~/.claude/agents/ 里的 Claude Code agent 会被直接读取。 同名时优先级：项目 .pi > 项目 .claude > 用户 .pi > 用户 .claude > 内置。

---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after writing significant code.
tools: read, grep, find, ls, bash
model: inherit
---

你是资深代码审查员……（正文即追加的系统提示词）

字段：name（缺省取文件名）、description（必填，决定何时被委派）、 tools（逗号分隔的 pi 内置工具名，缺省用 pi 默认工具集）、 model（如 anthropic/claude-haiku-4-5，inherit/缺省继承父会话）。

修改 agent 定义或 extension 后用 /reload 生效。

本仓库的 agents/code-reviewer.md 是一个示例（复刻 Claude Code 文档的经典例子）， 已通过 .pi/agents 软链在本项目内生效。

内置 agent 类型

• general-purpose — 全工具（read/bash/edit/write/grep/find/ls），研究复杂问题、多步任务。
• explore — 只读（read/grep/find/ls/bash），大范围代码搜索，只汇报结论和 path:line。
• plan — 只读，产出实施计划：步骤、关键文件、权衡、风险、验证策略。

worktree 隔离

当多个子 agent 需要并行改文件（或做高风险修改）时，让模型传 isolation: "worktree"：

1. spawn 前 git worktree add -b agent/<type>-<n>-<rand> <tmp目录> HEAD，子 agent 的 cwd 指向该目录；
2. 结束后无改动 → worktree 和分支自动删除，零痕迹；
3. 有改动 → 保留，工具结果中附带：worktree 路径、分支名、commit 列表 / diff stat / 未跟踪文件， 以及现成的 Review / Merge / Discard 命令。

注意：worktree 是 HEAD 的干净签出——父工作区未提交的改动、node_modules 等未跟踪文件都不在里面； 要求当前目录是有至少一个 commit 的 git 仓库。

已知限制

• 后台任务表存于内存，/reload、/new 或退出后 agent_output 查不到旧任务 （但子会话文件仍在，resume 仍可用）。
• 子 agent 以 --no-extensions 启动，因此拿不到其他 extension 注册的工具； 如需保留它们，把 buildSpawnArgs 里的 --no-extensions 换成 --exclude-tools agent,agent_output。
• tools 字段只对 pi 内置工具有意义（--tools 是允许名单）。

---

English

A pi extension that brings Claude Code-style subagents to pi. Pi intentionally ships without built-in sub-agents — this extension fills that gap:

• agent tool — the LLM delegates multi-step tasks to autonomous subagents (spawned as pi --mode json subprocesses with live progress rendering)
• Built-in agent types — general-purpose (full tools), explore (read-only search), plan (read-only architect), mirroring Claude Code's built-ins
• Custom agents from markdown — .pi/agents/*.md and ~/.pi/agent/agents/*.md, plus drop-in compatibility with existing Claude Code agents in .claude/agents/ and ~/.claude/agents/
• Parallel launches — multiple agent calls in one message run concurrently
• Background mode — run_in_background: true with completion notification, poll via agent_output
• Resume — subagent sessions persist; continue any finished agent by agentId with its context, agent type, and worktree restored
• Worktree isolation — isolation: "worktree" runs the agent in its own git worktree; auto-removed if unchanged, kept with branch/diff report if it made changes
• /agents command — list available agent types

Install: pi install git:github.com/linearuncle/pi-cc-subagent, or copy subagent.ts to ~/.pi/agent/extensions/ (global) / .pi/extensions/ (project-local), then /reload. No npm dependencies. MIT licensed. Full documentation above is in Chinese.