acpx — Multi-Agent Collaboration via ACP
Form teams of AI coding agents, run deliberations, build consensus, and delegate work — all through the Agent Client Protocol.
Prerequisites
CODEBLOCK0
Install the target agents you want to use (e.g., npm i -g @anthropic-ai/claude-code).
Quick Start: Single Agent
CODEBLOCK1
Quick Start: Multi-Agent Council
The fastest way to get multiple opinions on a task:
CODEBLOCK2
Council Protocol
The standard multi-agent collaboration pipeline:
CODEBLOCK3
Step-by-Step
1. ASSEMBLE — Create named sessions for each agent:
CODEBLOCK4
2. BRIEF — Send each agent the task with a role prefix:
CODEBLOCK5
3. DELIBERATE — Each agent reviews all other responses and revises:
CODEBLOCK6
4. CONVERGE — Orchestrator synthesizes a consensus plan.
5. EXECUTE — Delegate implementation to agents in parallel:
CODEBLOCK7
6. REVIEW — Cross-review implementations:
CODEBLOCK8
Quick Council Commands
CODEBLOCK9
Team Presets
Pre-configured role assignments for common scenarios. See references/roles.md for full definitions.
| Preset | Agents | Best For |
|---|
| INLINECODE2 | maintainer, perf, testing, security, dx | PR reviews, quality gates |
| INLINECODE3 |
security, skeptic, architect, dx, testing | Security-sensitive changes |
|
architecture_review | architect, perf, skeptic, maintainer, testing | Design decisions, tech debt |
|
devil_advocate | skeptic, skeptic, architect, maintainer | Go/no-go decisions, proposals |
|
balanced | neutral × N | General tasks, no specialization |
|
build_deploy | architect, testing, maintainer | Feature implementation |
Supported Agents
| Agent | Command | Install |
|---|
| Claude Code | INLINECODE8 | INLINECODE9 |
| Codex |
acpx codex |
npm i -g @openai/codex |
| OpenCode |
acpx opencode |
npm i -g opencode-ai |
| Gemini CLI |
acpx gemini |
npm i -g @anthropic-ai/gemini-cli |
| Cursor |
acpx cursor | Cursor app |
| GitHub Copilot |
acpx copilot |
npm i -g @githubnext/github-copilot-cli |
| Pi |
acpx pi | github.com/mariozechner/pi |
| Qwen Code |
acpx qwen |
npm i -g @qwen/qwen-code |
Agent Mode Switching
Set working modes (Claude Code example; other agents may vary):
| Mode | Behavior | Use When |
|---|
| INLINECODE22 | Plan only, no execution | Architecture, analysis |
| INLINECODE23 |
Ask before changes | Standard work |
|
acceptEdits | Auto-accept edits | Trusted refactoring |
|
dontAsk | Auto-accept everything | Batch tasks |
|
bypassPermissions | Skip all checks | CI/automation |
CODEBLOCK10
Session Management
CODEBLOCK11
Output & Permissions
CODEBLOCK12
Bidirectional Communication
Any agent can call any other agent through acpx:
CODEBLOCK13
Reference Files
- -
references/roles.md — All 8 role definitions (security, architect, skeptic, perf, testing, maintainer, dx, neutral) with prompt prefixes for Round 1 and Round 2, plus team presets with agent-to-role mappings. references/protocols.md — 7 collaboration patterns (fan-out, deliberation, role council, adversarial debate, sequential pipeline, DOVA hybrid, DCI structured) with acpx command examples, decision matrix, and cost estimates.
Gotchas
- - Mode not settable at creation: Use
set-mode after INLINECODE30 - session/update warnings: Claude Code adapter may emit
Invalid params — harmless - Dead session recovery: acpx auto-detects and reconnects, replaying mode settings
- No direct agent-to-agent messaging: All communication goes through the orchestrator
--format quiet is essential for piping: Returns only final text, no tool calls or thinking- 2 rounds is optimal: Research shows diminishing returns beyond 2 deliberation rounds
- Session resume preserves context: Use the same
-s name across rounds for continuity
acpx — 通过ACP实现多智能体协作
组建AI编码智能体团队，运行审议，建立共识，并分配工作——全部通过智能体客户端协议实现。
前置条件
bash
npm i -g acpx@latest
安装你想要使用的目标智能体（例如：npm i -g @anthropic-ai/claude-code）。
快速入门：单智能体
bash
一次性执行（无会话状态）
acpx claude exec 修复失败的测试
持久化多轮会话
acpx claude sessions new --name worker
acpx claude -s worker 分析认证模块
acpx claude -s worker 现在根据你的分析进行重构
快速入门：多智能体委员会
获取多个意见的最快方式：
bash
1. 组建团队（为每个智能体创建命名会话）
acpx claude sessions new --name claude-r && acpx codex sessions new --name codex-r && acpx gemini sessions new --name gemini-r
2. 第一轮：并行向所有智能体分发相同问题
acpx --format quiet claude -s claude-r 审查 src/auth.ts 的安全漏洞。请具体说明。 > /tmp/r1-claude.txt &
acpx --format quiet codex -s codex-r 审查 src/auth.ts 的安全漏洞。请具体说明。 > /tmp/r1-codex.txt &
acpx --format quiet gemini -s gemini-r 审查 src/auth.ts 的安全漏洞。请具体说明。 > /tmp/r1-gemini.txt &
wait
3. 第二轮：每个智能体查看所有回复并进行修订
acpx --format quiet claude -s claude-r 其他审查者说：\n[Codex]: $(cat /tmp/r1-codex.txt)\n[Gemini]: $(cat /tmp/r1-gemini.txt)\n\n修订你的评估。 > /tmp/r2-claude.txt &
acpx --format quiet codex -s codex-r 其他审查者说：\n[Claude]: $(cat /tmp/r1-claude.txt)\n[Gemini]: $(cat /tmp/r1-gemini.txt)\n\n修订你的评估。 > /tmp/r2-codex.txt &
acpx --format quiet gemini -s gemini-r 其他审查者说：\n[Claude]: $(cat /tmp/r1-claude.txt)\n[Codex]: $(cat /tmp/r1-codex.txt)\n\n修订你的评估。 > /tmp/r2-gemini.txt &
wait
4. 综合（由编排智能体执行）
echo === 最终审查 ===\n\n[Claude]: $(cat /tmp/r2-claude.txt)\n\n[Codex]: $(cat /tmp/r2-codex.txt)\n\n[Gemini]: $(cat /tmp/r2-gemini.txt)
委员会协议
标准的多智能体协作流程：
组建团队 → 分发问题 → 交叉讨论 → 形成共识 → 分工执行 → 交叉审查 → 交付成果
分步指南
1. 组建团队 — 为每个智能体创建命名会话：
bash
acpx claude sessions new --name council-claude
acpx codex sessions new --name council-codex
acpx opencode sessions new --name council-opencode
2. 分发问题 — 向每个智能体发送带有角色前缀的任务：
bash
acpx --format quiet claude -s council-claude [角色：架构师] 为我们的API设计缓存层。考虑：失效策略、TTL、旁路缓存与直写缓存。 > /tmp/r1-claude.txt
acpx --format quiet codex -s council-codex [角色：性能专家] 为我们的API设计缓存层。考虑：失效策略、TTL、旁路缓存与直写缓存。 > /tmp/r1-codex.txt
3. 交叉讨论 — 每个智能体审查所有其他回复并进行修订：
bash
ALL_RESPONSES=$(echo [Claude]: $(cat /tmp/r1-claude.txt)\n\n[Codex]: $(cat /tmp/r1-codex.txt))
acpx --format quiet claude -s council-claude 其他架构师说：\n$ALL_RESPONSES\n\n修订你的设计。解决提出的任何问题。 > /tmp/r2-claude.txt
acpx --format quiet codex -s council-codex 其他架构师说：\n$ALL_RESPONSES\n\n修订你的设计。解决提出的任何问题。 > /tmp/r2-codex.txt
4. 形成共识 — 编排智能体综合形成共识计划。
5. 分工执行 — 并行向智能体分配实现任务：
bash
acpx --approve-all claude -s exec-claude 基于此设计实现缓存层：$(cat /tmp/consensus.txt) &
acpx --approve-all codex -s exec-codex 为缓存层编写测试：$(cat /tmp/consensus.txt) &
wait
6. 交叉审查 — 交叉审查实现：
bash
acpx --format quiet codex -s council-codex 审查Claude的实现，检查bug和边界情况：\n$(cat /tmp/impl-claude.txt)
acpx --format quiet claude -s council-claude 审查Codex的测试，检查覆盖缺口：\n$(cat /tmp/tests-codex.txt)
快速委员会命令
bash
一行命令组建3智能体团队
acpx claude sessions new --name t1 && acpx codex sessions new --name t2 && acpx gemini sessions new --name t3
发射后不管（不等待）
acpx --no-wait --format quiet claude -s t1 任务... > /tmp/r1-t1.txt
收集所有第一轮结果
cat /tmp/r1-*.txt
审议后清理
acpx claude sessions close t1 && acpx codex sessions close t2 && acpx gemini sessions close t3
团队预设
常见场景的预配置角色分配。完整定义见 references/roles.md。
| 预设 | 智能体 | 最佳用途 |
|---|
| codereview | 维护者、性能、测试、安全、开发者体验 | PR审查、质量门禁 |
| securityaudit |
安全、质疑者、架构师、开发者体验、测试 | 安全敏感变更 |
| architecture_review | 架构师、性能、质疑者、维护者、测试 | 设计决策、技术债务 |
| devil_advocate | 质疑者、质疑者、架构师、维护者 | 通过/不通过决策、提案 |
| balanced | 中立 × N | 通用任务，无专业化 |
| build_deploy | 架构师、测试、维护者 | 功能实现 |
支持的智能体
| 智能体 | 命令 | 安装方式 |
|---|
| Claude Code | acpx claude | npm i -g @anthropic-ai/claude-code |
| Codex |
acpx codex | npm i -g @openai/codex |
| OpenCode | acpx opencode | npm i -g opencode-ai |
| Gemini CLI | acpx gemini | npm i -g @anthropic-ai/gemini-cli |
| Cursor | acpx cursor | Cursor应用 |
| GitHub Copilot | acpx copilot | npm i -g @githubnext/github-copilot-cli |
| Pi | acpx pi | github.com/mariozechner/pi |
| Qwen Code | acpx qwen | npm i -g @qwen/qwen-code |
智能体模式切换
设置工作模式（以Claude Code为例；其他智能体可能有所不同）：
| 模式 | 行为 | 使用场景 |
|---|
| plan | 仅计划，不执行 | 架构、分析 |
| default |
变更前询问 | 标准工作 |
| acceptEdits | 自动接受编辑 | 可信重构 |
| dontAsk | 自动接受所有 | 批量任务 |
| bypassPermissions | 跳过所有检查 | CI/自动化 |
bash
acpx claude -s worker set-mode plan
acpx claude -s worker set model opus # 或 sonnet
会话管理
bash
acpx claude sessions new --name worker # 创建命名会话
acpx claude sessions ensure # 如不存在则创建
acpx claude sessions list # 列出所有
acpx claude sessions show # 检查当前
acpx claude -s worker sessions history # 最近轮次
acpx claude -s worker status # pid、运行时间
acpx claude sessions close worker # 软关闭（保留历史）
##
