Claude Code Agent Farm
在 tmux 中并行编排 20+ 个 Claude Code 智能体，系统性修复 Bug、落地最佳实践，并通过锁机制避免多智能体冲突。
最低权限：默认 cc 别名为 claude --dangerously-skip-permissions，20–50 个代理以完全跳过权限模式运行并自动执行工具，这是与最小权限原则直接相悖的破坏性默认（扣至0）。用户确认：安装/工具脚本声称先询问再安装，双Ctrl+C强制关闭，但核心运行期间无逐操作确认（1）。数据流：监控面板、monitor state JSON、README详述两脚本架构，透明度尚可（2）。敏感数据：仅提及 ~/.claude/settings. 备份与损坏检查，无隐私/API密钥处理说明（1）。依赖安全：仅 typer/rich 两个核心依赖并设下限，攻击面小，但未提供锁定文件或审计（2）。外部效应：自动 git commit/push 到 origin，有 --skip-commit 等开关（2）。回滚：设置备份/恢复带轮转、git 提交留痕（2）。来源归属：作者、邮箱、仓库链接清晰（2）。
自洽性：README 内部有矛盾——提示词清单一处写 37 个、配置章节写 36 个可用；LICENSE 徽章与实际非标准附加条款不符（1）。依赖可用性：核心依赖极少且版本下限明确，但强依赖 claude/tmux/uv 等外部工具且 doctor 可校验（2）。失败信息：doctor 预检、usage-limit 检测、max_errors 阈值等有描述，但未见实际代码证据（2）。
受众与场景：覆盖34个技术栈、三类工作流、24个安装脚本，场景描述非常充分（3）。能力边界：明确说明非 Claude Code CLI 时监控/重启/上下文管理会退化或失效（2）。触发精度：CLI 选项与配置项一一对应并说明默认值（2）。环境适配：明确 POSIX Linux、Python 3.13+、tmux 要求，但明确不支持 macOS/Windows（2）。
信息架构：README 分节清晰但极长且提供的文本被截断（2）。安装说明：setup.sh + doctor + 补全安装，步骤完整（3）。命名稳定性：包名、命令名、会话名全文一致（2）。示例与FAQ：大量配置/命令示例，但无FAQ与故障排查章节（2）。已知限制：对其他CLI的caveat写得诚实，其余风险（成本、并发git冲突）说明有限（2）。许可证：LICENSE 为带 OpenAI/Anthropic 限制附加条款的修改版 MIT，非 OSI 兼容；pyproject 声称纯 MIT、元数据为 NOASSERTION，三者不一致（1）。版本与变更日志：仅 1.0.0 与 Beta 分类器，无 CHANGELOG（1）。维护责任：作者实名、Issues 链接存在，但无治理/响应承诺（2）。
输出可用性：HTML运行报告、富diff摘要、进度文档、监控面板均有描述（2）。边际价值：将Claude Code并行编排+锁协调+tmux监控打包为一键框架，定位独特、填补空白（3）。成本效益：默认20个代理、推荐至50个，运行于按token计费的LLM CLI之上，README对API成本几乎无提示或预算控制（1）。
主张可追溯：多数功能指向具体文件/命令（setup.sh、view_agents.sh、configs/*.）（2）。跨源印证：README与pyproject在许可证上冲突，提示词数量自相矛盾，34栈/31指南清单无法在提供文件内核验（1）。事实与推断区分：caveat章节明确区分了确定行为与预期退化，处理较好（2）。
- 默认要求 --dangerously-skip-permissions：20–50个代理可在无人确认的情况下修改、提交并推送你的代码库，切勿在生产仓库或含敏感配置的仓库中直接运行。
- 许可并非标准MIT：包含针对OpenAI/Anthropic及其关联方的限制性附加条款，禁止向其提供/部署/用于训练等，企业采用前需法务审查；pyproject的MIT声明与实际LICENSE不一致。
- 自动 git push 到 origin 可能把代理生成的未经审查代码推送到共享远端分支，建议始终使用 --skip-commit 或专用分支评审。
- 运行成本极高：默认20个并行LLM代理且自动重启，README几乎没有成本预算提示，务必先小规模试运行并设置用量上限。
- 协调机制依赖提示词而非代码（自述'仅靠提示文件实现'），锁与冲突预防的实际可靠性未经执行验证。
这个 Agent 能做什么，适合哪些场景？
Claude Code Agent Farm 是一个用 Python 3.13 编写的多智能体编排框架，可在 tmux 会话中并行运行最多 50 个 Claude Code 智能体（默认 20 个）。主脚本 claude_code_agent_farm.py 负责生成问题清单、在各个窗格中启动智能体、通过心跳文件和上下文百分比监控健康状态，并支持故障自动重启；辅助脚本 view_agents.sh 提供网格、聚焦、分屏等多种 tmux 查看模式。它支持 Bug 修复、最佳实践实施和多智能体协作三类工作流，预置 34 种技术栈配置、37 个提示词模板和 35 份最佳实践指南。协作工作流完全通过提示词实现：智能体在 /coordination/ 目录中用 JSON 注册表和锁文件认领工作，避免文件冲突。运行结束会生成 HTML 报告，并自动备份和恢复 ~/.claude/settings. 以防配置损坏。
端到端流程：1) 运行配置中 problem_commands 定义的类型检查、lint、测试命令（如 cargo check、bun run type-check），生成合并的问题文件；2) 在 tmux 会话 claude_agents 中逐个（交错启动，默认 10 秒）启动智能体，每个智能体在窗格中通过 cc 别名运行 Claude Code；3) 智能体随机选取问题块（chunk_size 可动态调整）或按最佳实践指南分块实施改进，完成后标记 [COMPLETED] 防止重复；4) Python 编排器通过心跳文件（.heartbeats/agent*.heartbeat）、上下文百分比解析和 tmux 窗格标题持续监控，上下文低于阈值（默认 20%）时自动清空，出错或心跳停滞超 2 分钟时自动重启并采用指数退避；5) 变更以 git 提交记录（支持 --commit-every N 增量提交），Ctrl+R 可向所有智能体广播 /clear；6) 运行结束生成 agent_farm_report_*.html 报告，并将监控状态写入 .claude_agent_farm_state. 供外部工具读取。协作模式下，智能体通过 /coordination/ 下的 active_work_registry.、planned_work_queue. 和 agent_locks/ 锁文件协调并行工作。
- 维护大型 Next.js 或 Python/FastAPI 代码库的团队，希望并行消化类型检查和 linter 积压的大量报错
- 采用现代框架但代码风格陈旧的工程团队，可用 35 份最佳实践指南系统性推进重构，进度文档在多次运行间保持连续
- 需要在单一代码库上执行大规模重构、补全类型注解或多方面性能优化的高级用户，适合协作智能体工作流的锁机制协调
- 希望对 Solana、Unreal Engine、Kubernetes AI 推理等小众技术栈做自动化清理的团队，可从 34 种预置配置中选择或自定义 JSON 配置
- 想在 CI/CD 或无人值守环境中运行的运维人员，可用 --no-monitor 模式跳过仪表盘直接启动
这个 Agent 有哪些优点和局限？
- 锁文件与 [COMPLETED] 标记机制解决多智能体并行修改同一文件的核心冲突问题，20+ 智能体可无冲突并行工作
- 上下文管理完善：自动清空低于阈值上下文、Ctrl+R 一键广播 /clear、自适应空闲超时（基于周期中位数的 3 倍）和指数退避重启
- 34 种技术栈预配置加自定义 JSON 支持，37 个提示词模板、35 份最佳实践指南开箱即用
- doctor 预检命令、设置自动备份/轮转恢复、HTML 运行报告和外部可读的状态文件，可观测性和故障恢复设计成熟
- cc 别名可指向任意交互式编码 CLI（如 OpenCode、Codex CLI），编排器不硬编码 claude 二进制
- 深度绑定 Claude Code 的监控能力：就绪检测（'Welcome to Claude Code!' 横幅）、上下文百分比解析、/clear 重置和使用限额检测在其他 CLI 上会退化或失效
- 需要 --dangerously-skip-permissions 权限模式运行，智能体可直接修改代码库和执行命令，安全风险需自行评估
- 每个智能体约消耗 500MB 内存，20+ 并行对本地硬件和 API 配额有实质成本压力
- 要求 Python 3.13+，运行时依赖较重（tmux、uv、direnv、项目自身工具链），setup 环境搭建成本不低
- 协作智能体工作流目前主要面向 Python FastAPI/Postgres 场景，其他栈需自行设计提示词
- GitHub 许可证字段显示 NOASSERTION，实际为 MIT+OpenAI/Anthropic Rider 的自定义许可，商用前需核查附加条款
如何安装或部署这个 Agent？
前置条件：Python 3.13+（由 uv 管理）、tmux、已安装并配置好的 Claude Code（claude 命令）、git、项目自身工具（如 Bun、mypy、ruff）、可选 direnv。
git clone https://github.com/Dicklesworthstone/claude_code_agent_farm.git
cd claude_code_agent_farm
chmod +x setup.sh
./setup.shsetup.sh 会创建 Python 3.13 虚拟环境、安装依赖、自动配置 cc 别名（alias cc="ENABLE_BACKGROUND_TASKS=1 claude --dangerously-skip-permissions"）并设置 direnv。运行 claude-code-agent-farm doctor --path /path/to/project 验证环境。
如何使用这个 Agent？
Bug 修复：claude-code-agent-farm --path /path/to/project --config configs/nextjs_config.
最佳实践实施：先将指南复制到项目（cp best_practices_guides/NEXTJS15_BEST_PRACTICES.md /path/to/project/best_practices_guides/），再运行 claude-code-agent-farm --path /path/to/project --config configs/nextjs_best_practices_config.
协作智能体模式：claude-code-agent-farm --path /project --prompt-file prompts/cooperating_agents_improvement_prompt_for_python_fastapi_postgres.txt --agents 5
快速试运行（5 个智能体、跳过 git 提交）：claude-code-agent-farm --path /project -n 5 --skip-regenerate --skip-commit
无头模式：加 --no-monitor --auto-restart。首次运行建议从 5-10 个智能体起步；每个智能体约占用 500MB 内存，默认上限 50 个。可通过 --agents、--chunk-size、--context-threshold、--commit-every 等 CLI 参数覆盖 JSON 配置。