Claude Squad 实战指南：用一个终端同时管理多个 Claude Code、Codex 与 AI Agent 任务

AI 编程工具进入 2026 年之后，一个很明显的变化是：我们不再只把 Claude Code、Codex、Gemini CLI、Aider 当成“聊天式代码助手”，而是开始把它们当成能在项目里持续执行的本地代理。

但单独开一个 AI CLI 很快会遇到瓶颈：

• 一个任务在跑测试时，你只能等；
• 一个任务需要你补充上下文时，整个队列就停住；
• 两个任务同时改代码，很容易把本地工作区弄乱；
• AI 改了什么，你必须不断切窗口、看 diff、查分支；
• 任务失败后，清理临时分支和 worktree 又是一堆手工活。

Claude Squad 解决的正是这个问题。它是一个终端 TUI 应用，可以在一个界面里管理多个本地 AI agent 实例，包括 Claude Code、Codex、Gemini CLI、Aider 等。每个任务都有自己的 tmux 会话、自己的 git worktree、自己的分支和自己的 diff 预览。你可以同时让一个 agent 修 bug，另一个补文档，第三个探索重构方案，然后逐个 review、追问、推送或丢弃。

截至 2026-06-26，官方仓库最新 release 是 v1.0.19，项目使用 Go 编写，许可证是 AGPL-3.0。官方 README 对它的定位很直接：管理多个本地 AI terminal agents，让你同时处理多个任务。

---

一、Claude Squad 到底是什么

先用一句话定义：

Claude Squad 是一个面向 AI CLI 的任务驾驶舱。它不替代 Claude Code 或 Codex，而是负责把多个 AI CLI 实例组织起来。

它的三层核心能力是：

层级	依赖	作用
终端会话	tmux	每个 AI agent 在独立会话里持续运行，可以 attach / detach
代码隔离	git worktree	每个任务在独立目录和独立分支里修改代码
统一操作台	Claude Squad TUI	在一个终端中创建任务、查看输出、查看 diff、切换任务、推送分支

官方截图大概长这样：

这张图里最关键的不是 UI 多炫，而是它把三件过去很分散的事情放到了一起：

1. 左侧管理任务实例：你可以看到多个 session 的状态、名称和变更量。
2. 右侧预览输出和 diff：不用反复切终端、切编辑器、敲 git diff。
3. 底部提供快捷键菜单：新建、打开、切换预览、checkout、resume、help 都在一个界面里完成。

它不是云端队列，也不是 SaaS agent 平台，而是一个本地开发者工具。所有 agent 仍然跑在你的机器上，使用你本地的 Git 仓库、终端、认证和 CLI。

---

二、为什么它能让你同时处理多个任务

单个 Claude Code 或 Codex CLI 最大的问题不是能力弱，而是工作通道只有一条。当它在跑测试、读文件、等待模型输出、请求你确认，或者陷入某个上下文问题时，你的注意力也被卡住。

Claude Squad 的思路是把“一个长任务”拆成“多个隔离任务通道”：

这带来几个实际好处。

1. 等待时间可以被填满

AI agent 经常会花时间：

• 扫描代码库；
• 安装依赖；
• 跑 npm test、go test、pytest；
• 读取错误日志；
• 根据失败结果再次修改；
• 等待你确认某个操作。

如果只有一个 CLI，你会被迫等待。如果有多个 session，A 任务跑测试时，你可以去看 B 任务的 diff，或者给 C 任务补一段提示词。

2. 代码修改天然隔离

Claude Squad 的重要设计是使用 git worktree。每个任务不是在你的主工作区直接改，而是在 ~/.claude-squad/worktrees/ 下创建独立目录。源码里默认分支名会使用 branch_prefix + sessionName，默认 branch_prefix 会根据当前用户名生成，例如 houshuai/ 这种形式。

这意味着：

• 任务 A 改动不会直接污染任务 B；
• 失败的探索可以直接删除 session；
• 成功的任务可以单独 checkout 或 push；
• 你可以在主工作区继续做自己的事。

3. 人类仍然掌握最后合并权

Claude Squad 的价值不是“让 AI 自动把代码合进主分支”。更合理的用法是：

AI agent 并行执行
-> 你逐个看 preview
-> 你逐个看 diff
-> 你补充 prompt 或要求修正
-> 通过后推送分支
-> 仍然走 PR / review / CI

也就是说，它把 AI 变成多个后台执行者，但没有取消工程里的审查门槛。

---

三、安装与前置条件

Claude Squad 会安装为 cs 命令。

1. 前置条件

官方 README 列出的前置条件是：

tmux
gh

也就是：

• tmux：负责创建和恢复独立终端会话；
• gh：GitHub CLI，用来推送、同步、打开分支等；
• 至少一个可用 AI CLI：例如 claude、codex、gemini 或 aider。

macOS 可以这样准备：

brew install tmux gh
gh auth login

如果你默认使用 Claude Code，需要确保 claude 在 shell 里可用：

which claude
claude --version

如果你想用 Codex：

export OPENAI_API_KEY="<your_key>"
codex --version

2. Homebrew 安装

官方 README 给出的 Homebrew 安装方式是：

brew install claude-squad
ln -s "$(brew --prefix)/bin/claude-squad" "$(brew --prefix)/bin/cs"

安装后检查：

cs version
cs debug

cs debug 很有用，它会告诉你配置文件、状态文件等路径。

3. 手动安装

也可以使用官方安装脚本：

curl -fsSL https://raw.githubusercontent.com/smtg-ai/claude-squad/main/install.sh | bash

默认会把二进制放到：

~/.local/bin

如果你想换命令名：

curl -fsSL https://raw.githubusercontent.com/smtg-ai/claude-squad/main/install.sh | bash -s -- --name squad

---

四、第一次启动

进入一个 Git 仓库，然后启动：

cd ~/project/my-app
git status --short
cs

启动前建议先保证主工作区干净：

git status --short
git pull --rebase

原因很简单：Claude Squad 新建 worktree 时通常会基于当前 HEAD 创建独立分支。主分支越干净，每个 AI session 的起点越清晰，后续 review 和合并越少出意外。

启动后，常用操作如下。

操作	快捷键	说明
新建 session	n	创建一个新任务
带 prompt 新建 session	N	新建时直接输入任务说明
上下移动	up/k、down/j	在 session 列表中移动
打开当前 session	enter 或 o	attach 到 agent 里继续追问
从 agent 返回 TUI	ctrl-q	detach 回 Claude Squad
切换 preview / diff	tab	看运行输出或代码差异
checkout / 暂停	c	提交修改并暂停 session
resume	r	恢复暂停的 session
帮助页	?	查看当前版本实际快捷键
退出	q	退出 TUI

版本提示：官方 README 和源码里个别快捷键说明曾出现过不一致，例如 push branch 在 README 中写过 s，而当前 main 分支 keys.go 映射的是 p。实操时以 TUI 底部菜单和 ? 帮助页为准。

---

五、它内部是怎么工作的

理解内部机制后，你会更清楚它适合什么、不适合什么。

1. 创建 session

当你按 n 或 N 创建一个 session，Claude Squad 会为它生成一个名称。这个名称会影响：

• TUI 里的 session 标题；
• tmux session 名；
• Git 分支名；
• worktree 目录名的一部分。

如果你用 N，可以在创建时直接输入初始 prompt。这个方式适合把任务从一开始就讲清楚。

2. 创建 git worktree

Claude Squad 会在配置目录下维护 worktree：

~/.claude-squad/worktrees/

源码中 worktree 路径大致由“分支名清洗结果 + 时间戳”组成。这样做有两个好处：

• 不会和主项目目录混在一起；
• 同名任务多次创建也不容易撞目录。

新任务默认会从当前 HEAD 创建分支；如果选择已有分支，它会尝试从本地或远端分支创建 worktree。

3. 启动 tmux

每个 session 都会有一个 tmux 会话。AI CLI 实际运行在这个会话里，所以即使你 detach 回 Claude Squad，agent 仍然可以在后台继续执行。

这就是它能“同时处理多个任务”的关键：多个 tmux session 同时存在，Claude Squad 只是把它们统一展示出来。

4. 捕获 preview 和 diff

Claude Squad 会捕获 tmux pane 内容作为 preview，也会计算 worktree 的 diff 统计和 diff 内容。你不用每次都手动：

tmux attach -t xxx
git -C /path/to/worktree diff

TUI 已经把这两个视角放在一起：

• preview：看 agent 正在想什么、跑什么命令、卡在哪里；
• diff：看它到底改了哪些文件、加了多少行、删了多少行。

5. checkout、pause、resume

当一个 session 暂停时，Claude Squad 会尽量保留分支，移除 worktree，并把状态标成 paused。恢复时再重新创建 worktree 并恢复 tmux session。

这对长时间任务很重要：你不需要一直保留所有临时目录，也不需要每次从零开始。

---

六、配置 profiles：在 Claude、Codex、Aider、Gemini 之间切换

配置文件默认在：

~/.claude-squad/config.json

你可以用：

cs debug

确认当前机器上的真实路径。

官方 README 提供了 profiles 配置方式。一个实用版本可以这样写：

{
  "default_program": "claude",
  "auto_yes": false,
  "daemon_poll_interval": 1000,
  "branch_prefix": "ai/",
  "profiles": [
    {
      "name": "claude",
      "program": "claude"
    },
    {
      "name": "codex",
      "program": "codex"
    },
    {
      "name": "aider",
      "program": "aider --model ollama_chat/gemma3:1b"
    },
    {
      "name": "gemini",
      "program": "gemini"
    }
  ]
}

字段解释：

字段	作用
default_program	默认选中的 profile 名，或直接作为命令执行
profiles[].name	TUI 创建 session 时显示的 profile 名
profiles[].program	实际启动的 shell 命令
auto_yes	是否自动接受部分提示，建议默认关闭
daemon_poll_interval	auto-yes 模式下轮询 session 的间隔，单位毫秒
branch_prefix	创建分支时使用的前缀

也可以临时指定 program：

cs -p "codex"
cs -p "gemini"
cs -p "aider --model sonnet"

如果配置了多个 profile，新建 session 的 overlay 会提供 profile 选择。这样你可以让不同 agent 做不同类型的任务：

• Claude Code：复杂代码理解、跨文件修改；
• Codex：代码生成、测试修复、命令行工程任务；
• Aider：适合明确文件范围的小步修改；
• Gemini CLI：适合长上下文阅读或交叉验证。

---

七、auto-yes 要慎用

Claude Squad 支持：

cs -y

也就是 experimental auto-yes / yolo 模式。它会尝试自动接受 Claude Code 和 Aider 等工具中的确认提示，让任务更像后台自动执行。

这个功能很诱人，但要分场景使用。

适合 auto-yes 的任务：

• 只读分析；
• 生成文档草稿；
• 修复格式化；
• 更新测试快照；
• 在临时分支里做低风险探索；
• 已经明确限制了文件范围和命令范围的任务。

不适合 auto-yes 的任务：

• 涉及数据库、线上环境、云资源、密钥、账单；
• 可能删除文件或批量重命名；
• 会修改 CI、权限、部署脚本；
• 会运行不可预测的 shell 脚本；
• 你还没有明确验收标准。

我的建议是：

默认不开 auto-yes。
只有在任务边界很清楚、仓库可恢复、结果必须经过 review 时才开。

更稳的做法是在 prompt 里加硬约束：

只允许修改 src/components/LoginForm.tsx 和对应测试文件。
不要修改 package.json。
不要执行 git commit、git push、rm -rf 或任何部署命令。
完成后运行 npm run typecheck，并停下来总结。

---

八、实战：同时推进三个开发任务

假设你在一个 Docusaurus / React / TypeScript 项目里，今天有三个任务：

1. 修复 npm run typecheck 报错；
2. 给一个新工具页补文档和截图说明；
3. 探索把一个复杂组件拆成更小组件，但不确定是否值得合并。

这些任务互相独立，适合用 Claude Squad 并行。

1. 准备仓库

cd ~/project/my-site
git status --short
git pull --rebase
cs

如果当前工作区已经有未提交修改，建议先处理掉：

git stash push -m "wip before claude-squad"

或者提交到你自己的分支。不要让 AI session 从一个脏状态开始，否则后面 diff 会很难判断哪些是 AI 改的。

2. 创建第一个 session：修 typecheck

按 N，选择 claude profile，输入：

任务：修复当前仓库的 npm run typecheck 报错。

约束：
- 先运行 npm run typecheck，记录关键错误。
- 只做最小必要修改，不做无关重构。
- 如果涉及类型定义，优先修正类型边界，不要用 any 直接绕过。
- 修改后再次运行 npm run typecheck。
- 完成后停下来总结改了哪些文件、为什么这样改、还有哪些风险。

这个 session 开始跑后，不要一直盯着它。返回 Claude Squad TUI，创建第二个任务。

3. 创建第二个 session：补文档

按 N，选择 codex 或 claude：

任务：为 tools 页面新增一段使用说明和一个最小示例。

约束：
- 先阅读 src/pages/tools.tsx 和相关组件。
- 保持现有视觉风格，不引入新的 UI 库。
- 文案用中文，避免营销口吻。
- 如果新增用户可见文本，按项目约定处理 i18n。
- 修改后运行 npm run typecheck。

文档类任务通常更适合并行，因为它和 typecheck 修复可能不会碰同一批文件。如果它们会改同一文件，就不要并行开。

4. 创建第三个 session：探索重构

按 N：

任务：探索 src/components/Recommendation/RecommendationCard.tsx 是否值得拆分。

约束：
- 这是 spike，不要求最终合并。
- 先阅读当前组件和调用方，列出拆分收益和风险。
- 如果要改代码，只创建一个小范围实验分支。
- 不要修改样式视觉结果。
- 完成后给出建议：保留现状、轻量拆分，还是完整重构。

这种探索任务最适合 Claude Squad：做得好可以保留分支，做得不好直接删除 session，不污染主线。

5. 轮流看 preview 和 diff

接下来你的工作不是“等 AI 完成”，而是像 tech lead 一样做调度：

你看到的状态	该做什么
preview 显示测试在跑	切到其它 session
preview 显示 agent 卡住	o attach 后补充上下文
diff 很大但任务很小	要求它收敛到最小修改
diff 改了无关文件	要求 revert 无关修改
类型修复用了 any	要求给出更严格类型方案
spike 结果不值得合并	删除 session 或保留记录即可

不要把“多个 agent 同时工作”理解成“你不用管”。更好的模型是：

AI 负责并行探索和执行
你负责边界、验收、取舍和合并

---

九、review 与交付流程

一个 session 完成后，不要急着推送。先看 diff：

tab -> diff view

重点看五件事：

1. 是否只改了任务范围内的文件；
2. 是否引入了大而无关的重构；
3. 是否隐藏了错误，比如删测试、跳过类型、吞异常；
4. 是否修改了配置、依赖、CI、部署脚本；
5. 是否真的运行了你要求的验证命令。

如果需要追问：

o -> attach

补充类似这样的 prompt：

这个 diff 改动过大。请只保留修复 typecheck 必需的最小修改。
撤回所有文案、样式和无关重命名。
完成后重新运行 npm run typecheck，并解释每个保留修改的必要性。

当结果可接受后，再进行交付。

根据当前版本的 TUI 菜单，你可能会看到 push branch 对应 p 或 s。按 ? 查看实际快捷键。推送后建议仍然走 PR：

gh pr create --fill

或者让 Claude Squad 打开分支页面，再由你手动创建 PR。

---

十、提示词模板：让并行任务更稳

Claude Squad 的效果很大程度取决于 session 创建时的 prompt。并行任务最怕三件事：

• 多个 agent 同时改同一文件；
• agent 不知道验收标准；
• agent 自作主张扩大任务范围。

可以使用这个通用模板：

任务：
<一句话说明要完成什么>

背景：
<相关文件、报错、用户场景、业务约束>

允许修改：
- <文件或目录 1>
- <文件或目录 2>

禁止修改：
- <敏感文件或目录>
- package.json，除非你先解释为什么必须改
- CI / deploy / secret / env 配置

执行步骤：
1. 先阅读相关文件，不要直接改。
2. 总结你看到的问题和计划。
3. 只做最小必要修改。
4. 运行验证命令。
5. 如果验证失败，最多修两轮；仍失败就停下来说明原因。

验收标准：
- <命令通过>
- <行为符合预期>
- <diff 不包含无关改动>

完成后输出：
- 改了哪些文件
- 为什么这样改
- 运行了哪些验证
- 剩余风险

对并行任务，最好再加一句：

不要修改任何与其它任务共享的核心文件；如果你认为必须修改，先停下来说明原因。

这句话可以显著减少多个 session 互相踩同一片代码的概率。

---

十一、适合和不适合 Claude Squad 的任务

适合的任务

场景	为什么适合
多个互不相关的小 bug	各自独立分支，最后逐个 review
文档、示例、测试补充	风险较低，容易验收
spike / 技术探索	失败可以直接丢弃 worktree
修复不同模块的类型错误	每个 session 聚焦一个模块
多 agent 交叉验证	Claude 写方案，Codex 做另一个实现，最后人比较

不适合的任务

场景	风险
多个任务同时改同一核心文件	合并冲突和行为回归概率高
大型架构重构	上下文和 review 成本都高
线上运维操作	auto-yes 和 CLI 权限风险大
涉及密钥、账单、权限	不应该交给后台自动代理
验收标准不清楚	并行只会放大混乱

一个简单判断：

如果任务可以拆成独立 PR，适合 Claude Squad。
如果任务必须多人会议先统一方案，不要直接开多个 agent 并行改。

---

十二、和 tmux、git worktree 手动方案相比

你当然可以自己手动做：

git worktree add ../task-a -b ai/task-a
git worktree add ../task-b -b ai/task-b
tmux new -s task-a
tmux new -s task-b

然后在每个 tmux session 里分别运行：

claude
codex
aider

这套手工方案也能工作。但当 session 多了以后，你会开始重复处理：

• 哪个 task 在哪个 tmux session；
• 哪个 worktree 对应哪个分支；
• 哪个 agent 已经完成；
• 哪个 diff 值得看；
• 哪个分支应该推送；
• 哪个 worktree 该清理。

Claude Squad 的价值就是把这些胶水工作产品化。它不是发明了 tmux 或 git worktree，而是把它们组合成了一个适合 AI agent 的操作界面。

---

十三、常见问题和排障

1. 新 session 启动失败

官方 FAQ 提到，如果出现类似 “timed out waiting for tmux session” 的错误，优先更新底层 program，比如 claude。

可以检查：

tmux -V
which claude
claude --version
cs debug

2. gh 相关操作失败

先确认 GitHub CLI 登录状态：

gh auth status

如果公司内网或私有 GitHub Enterprise，需要确认 gh 的 host 配置和仓库 remote 是否一致。

3. worktree 太多

先在 Claude Squad 里删除不需要的 session。必要时检查：

git worktree list
git worktree prune

如果你要手动清理 ~/.claude-squad/worktrees/，先确认没有正在运行的 session。不要在 agent 正在执行时直接删目录。

4. 分支冲突

多个 session 同时改同一文件时，冲突是正常的。解决方法不是让更多 agent 自动合并，而是减少并行粒度：

• 一个 session 负责一个模块；
• 一个 session 负责一个 PR；
• 共享核心文件交给人工或单独 session；
• 创建新 session 前先更新主分支。

5. 任务一直跑偏

通常不是 Claude Squad 的问题，而是 prompt 不够明确。回到 session，补充：

停止当前方向。
请先列出你已经改过的文件。
撤回与目标无关的修改。
然后只围绕下面这个验收标准继续：...

---

十四、我的推荐工作流

我更推荐把 Claude Squad 放在“日常开发第二工作台”的位置，而不是让它接管所有开发。

一个稳妥的日常流程是：

早上：
  更新主分支，确认工作区干净

规划：
  把任务拆成 2-4 个互不冲突的小 session

执行：
  让 agent 并行做初稿、修复、测试、文档和 spike

中途：
  只在 preview 卡住或 diff 扩散时介入

收敛：
  逐个看 diff，要求最小化修改

交付：
  推送单独分支，走 PR / CI / review

清理：
  删除失败 session，prune 多余 worktree

我不建议一次开太多 session。对大多数个人开发者，2 到 4 个并发任务已经足够。再多以后，你的 review 带宽会成为瓶颈，AI 产出的分支也会互相等待合并。

---

十五、结论

Claude Squad 的核心价值不是“多开几个 AI 窗口”，而是把 AI 编程任务变成了更工程化的工作单元：

• 一个任务一个 session；
• 一个 session 一个 worktree；
• 一个 worktree 一个 branch；
• 一个 branch 一个可 review 的 diff；
• 一个 diff 最终由人决定是否进入主线。

这套模型非常适合 AI native 开发：让 agent 在后台并行推进低耦合任务，让人类把精力放在边界、质量、取舍和合并上。

如果你已经在用 Claude Code、Codex、Aider 或 Gemini CLI，并且经常遇到“这个任务在跑，我只能等”的情况，Claude Squad 值得纳入工具箱。它不会替你做工程判断，但会把多任务 AI 协作的基础设施补齐。

参考链接：

• smtg-ai/claude-squad 官方仓库
• Claude Squad 官方站点
• Claude Squad v1.0.19 release