claude-squad - 终端多 Agent 并行管理器

claude-squad — 终端多 Agent 并行管理器

数据采集：2026-10-23（GitHub API 实抓 + README / 源码实读）仓库：https://github.com/smtg-ai/claude-squad ｜主页：https://smtg-ai.github.io/claude-squad/

一句话

它就三件事：tmux 起隔离终端会话、git worktree 隔离代码库、一个 TUI 让你在中间来回切。

5 分钟装完，零外部依赖（本机已有 tmux + git + gh 即可），是这条赛道里最轻的方案。

项目总览

维度	评价
项目类型	终端多会话管理器（TUI），并行的最小可用形态
技术壁垒	低 — 就是 tmux + worktree 的封装，但把”并行 agent”这件事的心智负担降到最低
学习价值	中高 — 极小代码量的 Go 项目，读完就懂并行 agent 的全部工程要点（隔离、恢复、diff 快照）
商业价值	低 — 纯开源无商业模式，但正因如此没有关停风险（对比 vibe-kanban）
适合人群	已在 tmux 里干活、只想要并行不想换来换去的个人开发者
核心创新	无新意，胜在”够用且不折腾”

硬数据（2026-10-23 GitHub API 实抓）

指标	值
⭐ Stars	8,656
Forks	623
Contributors	20
Open issues	50
建仓	2025-03-09
最近推送	2026-08-20 ⚠️ 约两个月未更新
最新版本	v1.0.20（2026-08-20）
主语言	Go
License	AGPL-3.0
Topics	claude-code, cli, codex, opencode, vibe-coding

对比同赛道：Multica 1,861 open issues / 357 contributors / 每天推送；Nimbalyst 812 / 60 / 每天推送。claude-squad 只有 50 个 issue，但两个月零提交。这是两种完全不同的健康度模式。

工作原理（三步）

README 原文：

tmux 创建隔离的终端会话
git worktrees 隔离代码库，让每个 session 跑在自己的分支上
一个简单的 TUI 界面做导航和管理

支持任意 agent CLI——通过 -p 传命令即可：

cs -p "codex"                    # OpenAI Codex
cs -p "gemini"                   # Gemini CLI
cs -p "aider --model ollama_chat/gemma3:1b"   # Aider + 本地模型

安装

# Homebrew（装出 `cs` 和 `claude-squad` 两个名）
brew install claude-squad
ln -s "$(brew --prefix)/bin/claude-squad" "$(brew --prefix)/bin/cs"

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

前置依赖：tmux + gh（GitHub CLI）。Windows 不支持（依赖 tmux）。

快捷键

键	动作
`n`	新建 session
`N`	带 prompt 新建 session
`D`	杀掉选中 session
`↑/j` `↓/k`	上下移动选择
`↵/o`	attach 到选中 session 重新提示
`ctrl-q`	detach（脱离但不杀）
`s`	提交并推送分支到 GitHub
`c`	checkout：提交改动并暂停 session
`r`	恢复被暂停的 session
`tab`	在 preview 窗格和 diff 窗格之间切换
`shift-↓/↑`	在 diff 视图滚动
`?`	帮助菜单

Flags：

-y / --autoyes（实验性）：自动接受所有提示，Claude Code 与 Aider 均适用
-p / --program：新 session 启动的程序
cs debug：打印配置与日志的绝对路径（排查时很有用，日志不在 ~/.claude-squad/ 时尤其需要）

配置

~/.claude-squad/config.json（确切路径用 cs debug 查）：

{
  "default_program": "claude",
  "profiles": [
    { "name": "claude", "program": "claude" },
    { "name": "codex",  "program": "codex" },
    { "name": "aider",  "program": "aider --model ollama_chat/gemma3:1b" }
  ]
}

定义了多个 profile 后，新建 session 时会弹出 profile 选择器（←/→ 切换）。未定义 profiles 时直接用 default_program。

值得学的工程细节（近半年两次高质量修复）

1. tmux server 挂掉后的实例恢复（v1.0.20, #322）

问题：tmux server 消失（重启 / 崩溃 / tmux kill-server）时所有 session 一起没了，但 state.json 里的实例仍记为 Running。下次启动时 tmux attach-session 对着不存在的 session 会 fork 成功然后自己 exit 1，于是 pty.Start 不报错、Restore 报成功，实际什么都没挂上：

ERROR tmux.go:238: error capturing pane content in status monitor: exit status 1

实例卡在 Running 但 preview 空白，r 恢复又只对 Paused 生效，退出路径只剩杀实例或 cs reset。

修复三处：Restore 检查 session 是否存在并返回 ErrSessionNotFound 哨兵错误；恢复时把已死的 session 标为 Paused 而非 Running（worktree 和分支还在磁盘上，Resume 能从同一个 Program 重建）；Resume 在 worktree 仍有效时不再跑 gitWorktree.Setup，因为 setupFromExistingBranch 会先 worktree remove -f + os.RemoveAll 再 add，正常 Pause 时目录已删无所谓，但新恢复路径下会丢掉未提交的工作——所以这个改动是非破坏性的。

顺带一个 Go 的坑：Storage.LoadInstances 在第一个 FromInstanceData 失败时就整体中止，一个死 session 会掩盖掉其他所有实例。这是所有”批量加载持久化状态”代码都要注意的。

2. 从已有分支创建的 session 丢失 base commit（#315）

setupNewWorktree 会解析 HEAD 赋给 g.baseCommitSHA，但 setupFromExistingBranch 从来没设过它。于是 diff.go 执行 git diff "" → exit 128，每个 session 一生都在刷这条警告，diff 窗格永久空白，且 "base_commit_sha": "" 会持久化在 state.json 里，重启也不清。

修复：两条路径（本地分支 / remote-tracking）都解析 worktree 的 HEAD 并存下来，让 “base” 统一为 session 启动时的那个 commit。

性能：完整 diff 只算选中实例（#279）——500ms 一次的 metadata tick 原本给 N 个 session 各存一份完整 git diff 字符串，但 diff 窗格一次只渲染一个。现在非选中实例只跑 git diff --numstat 拿增删行数，内存有界。

潜在坑

⚠️ 两个月没提交（最后 push 2026-08-20，v1.0.20）。不活跃 ≠ 不稳定，但别把它当长期依赖。
Windows 不支持（依赖 tmux）。这在 Windows 用户群里是硬门槛——要在这台机器上用，得先上 WSL。
需要 tmux + gh，gh 是为了 s（提交并推送）功能。
无 issue 跟踪、无 review 流程、无团队、无 web UI（虽然仓库里有 web/ Next.js 目录和 daemon/ 目录，说明作者在往常驻服务 + Web UI 方向走，但目前发布的仍是 TUI）。
AGPL-3.0：对内部自用完全无义务（AGPL 的网络条款只在”修改后通过网络提供服务”时触发，本地 CLI 不沾）；但对外分发修改版要开源。注意这与 Multica 的 source-available 是两种不同的限制。
tmux attach-session 对不存在的 session 会 fork 成功再 exit 1——这个坑已被上游修，但如果你 fork 或回退版本要注意。
-y（autoyes）标为实验性，全自动接受提示有风险。

赛道位置

claude-squad 是这条赛道的下界：它证明了”多 agent 并行”这件事本身只需要 tmux + worktree 就能成立，剩下所有复杂度（看板、审批、团队、审计）都是你真的需要多人协作时才该付的代价。

对比见 [[开源项目分析/Agent协作工作台/Agent协作工作台赛道对比|Agent 协作工作台赛道对比]]。

参考

[[开源项目分析/Agent协作工作台/Agent协作工作台赛道对比|Agent 协作工作台赛道对比]] — 四个工具的横向对比与选型
[[开源项目分析/Agent协作工作台/Nimbalyst-本地优先的可视化Agent工作台|Nimbalyst]] — 同赛道的可视化重方案（Crystal 的继任者）
[[开源项目分析/Agent协作工作台/Multica-人机同编的Agent协作工作台|Multica]] — 同赛道的团队级重方案
[[开发工具链/Git/Git工作流|Git 工作流]] — worktree 隔离的用法与坑
[[开源项目分析/AI编码工程化/Ralph-Autonomous-AI-Coding-Loop|Ralph]] — 另一种”让 agent 一直跑”的思路（循环 + 全新 context）