claude-squad

Claude Squad 是一个终端应用，用于在独立的 Git 工作区中管理多个 AI 终端代理，支持 Claude Code、Codex、Gemini、Aider、OpenCode、Amp 等本地代理，从而同时推进多个任务。

主要能力

• 在后台完成任务，包括 yolo / 自动接受模式。
• 在一个终端窗口中管理多个实例与任务。
• 在应用变更前审查改动，在推送前检出变更。
• 每个任务拥有独立的 Git 工作区，避免冲突。

安装与启动

通过 Homebrew 或手动安装时，Claude Squad 会以 cs 命令安装到系统中。也可以运行以下命令安装，将 cs 二进制文件放入 ~/.local/bin：

若要为二进制文件使用自定义名称，可自行命名。启动应用时使用 cs。

注意：默认程序是 claude，建议使用最新版本。

与其他 AI 助手配合

• 对于 Codex：设置 API 密钥 export OPENAI_API_KEY=<your_key>
• 启动特定助手：
  • Codex：cs -p "codex"
  • Aider：cs -p "aider ..."
  • Gemini：cs -p "gemini"

可通过修改配置文件（使用 cs debug 定位）将特定助手设为默认。

界面操作

屏幕底部菜单显示可用命令：

• n — 创建新会话
• N — 带提示词创建新会话
• D — 终止（删除）选中的会话
• ↑/j、↓/k — 在会话间导航
• ↵/o — 附加到选中会话以重新提示
• ctrl-q — 从会话分离
• s — 提交并将分支推送到 GitHub
• c — 检出。提交更改并暂停会话
• r — 恢复暂停的会话
• ? — 显示帮助菜单
• tab — 在预览标签页与差异标签页之间切换
• q — 退出应用
• shift-↓/↑ — 在差异视图中滚动

配置与配置文件

Claude Squad 将配置存储在 ~/.claude-squad/config.json。运行 cs debug 可查看确切路径。

Profiles 允许定义多个命名的程序配置，并在创建新会话时切换。当定义了多个 profile 时，会话创建浮层会显示 profile 选择器，可用 ← / → 导航。

要配置 profiles，在配置文件中添加 profiles 数组，并将 default_program 设置为默认选中的 profile 名称。每个 profile 有两个字段。

若未定义任何 profiles，Claude Squad 直接使用 default_program 作为启动命令（默认为 claude）。

限制与问题排查

• 如果出现类似 failed to start new session: timed out waiting for tmux session 的错误，请将底层程序（例如 claude）更新到最新版本。

技术实现

• 使用 tmux 为每个代理创建隔离的终端会话。
• 使用 git worktrees 隔离代码库，使每个会话在自己的分支上工作。
• 提供简单的 TUI 界面，便于导航和管理。