[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-Dicklesworthstone--claude_code_agent_farm":3,"tool-Dicklesworthstone--claude_code_agent_farm":61},[4,18,26,36,44,52],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",142651,2,"2026-04-06T23:34:12",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107888,"2026-04-06T11:32:50",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":10,"last_commit_at":50,"category_tags":51,"status":17},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,"2026-04-06T11:19:32",[35,15,13,14],{"id":53,"name":54,"github_repo":55,"description_zh":56,"stars":57,"difficulty_score":10,"last_commit_at":58,"category_tags":59,"status":17},4292,"Deep-Live-Cam","hacksider\u002FDeep-Live-Cam","Deep-Live-Cam 是一款专注于实时换脸与视频生成的开源工具，用户仅需一张静态照片，即可通过“一键操作”实现摄像头画面的即时变脸或制作深度伪造视频。它有效解决了传统换脸技术流程繁琐、对硬件配置要求极高以及难以实时预览的痛点，让高质量的数字内容创作变得触手可及。\n\n这款工具不仅适合开发者和技术研究人员探索算法边界，更因其极简的操作逻辑（仅需三步：选脸、选摄像头、启动），广泛适用于普通用户、内容创作者、设计师及直播主播。无论是为了动画角色定制、服装展示模特替换，还是制作趣味短视频和直播互动，Deep-Live-Cam 都能提供流畅的支持。\n\n其核心技术亮点在于强大的实时处理能力，支持口型遮罩（Mouth Mask）以保留使用者原始的嘴部动作，确保表情自然精准；同时具备“人脸映射”功能，可同时对画面中的多个主体应用不同面孔。此外，项目内置了严格的内容安全过滤机制，自动拦截涉及裸露、暴力等不当素材，并倡导用户在获得授权及明确标注的前提下合规使用，体现了技术发展与伦理责任的平衡。",88924,"2026-04-06T03:28:53",[14,15,13,60],"视频",{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":76,"owner_email":76,"owner_twitter":77,"owner_website":78,"owner_url":79,"languages":80,"stars":89,"forks":90,"last_commit_at":91,"license":92,"difficulty_score":93,"env_os":94,"env_gpu":95,"env_ram":95,"env_deps":96,"category_tags":105,"github_topics":106,"view_count":32,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":111,"updated_at":112,"faqs":113,"releases":128},5002,"Dicklesworthstone\u002Fclaude_code_agent_farm","claude_code_agent_farm","Orchestration framework for running 20+ Claude Code agents in parallel: automated bug fixing, best-practices sweeps, lock-based coordination, and real-time tmux monitoring","claude_code_agent_farm 是一个强大的编排框架，旨在让多个 Claude Code AI 代理并行工作，以系统化地改进代码库。它解决了大型项目中单靠人工或单个 AI 难以高效完成的重复性任务难题，例如自动修复大量 Bug、统一实施最佳实践规范，或在多技术栈环境中进行协同开发。\n\n这款工具特别适合需要处理大规模代码重构、维护复杂遗留系统或追求极致开发效率的软件工程师与技术团队。通过独特的基于锁的协调机制，它能有效防止多个并行代理在修改同一文件时产生冲突，确保操作安全有序。\n\n其技术亮点在于支持同时运行 20 至 50 个代理实例，并兼容 Next.js、Python、Rust 等 34 种主流技术栈。用户不仅可以实时通过 tmux 监控每个代理的工作状态和心跳，还能享受自动上下文管理、智能故障恢复以及详细的 Git 提交报告等功能。此外，项目内置了完善的环境预检与一键安装脚本，大幅降低了多代理系统的部署门槛，让开发者能轻松组建属于自己的\"AI 代码农场”，显著提升工程生产力。","# Claude Code Agent Farm 🤖🚜\n\n> Orchestrate multiple Claude Code agents working in parallel to improve your codebase through automated bug fixing or systematic best practices implementation\n\n[![Python 3.13+](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.13+-blue.svg)](https:\u002F\u002Fwww.python.org\u002Fdownloads\u002F)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT%2BOpenAI%2FAnthropic%20Rider-blue.svg)](.\u002FLICENSE)\n[![Code style: ruff](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fcode%20style-ruff-000000.svg)](https:\u002F\u002Fgithub.com\u002Fastral-sh\u002Fruff)\n\n## 🎯 What is this?\n\nClaude Code Agent Farm is a powerful orchestration framework that runs multiple Claude Code (`cc`) sessions in parallel to systematically improve your codebase. It supports multiple technology stacks and workflow types, allowing teams of AI agents to work together on large-scale code improvements.\n\n### Key Features\n\n- 🚀 **Parallel Processing**: Run 20+ Claude Code agents simultaneously (up to 50 with `max_agents` config)\n- 🎯 **Multiple Workflows**: Bug fixing, best practices implementation, or coordinated multi-agent development\n- 🤝 **Agent Coordination**: Advanced lock-based system prevents conflicts between parallel agents\n- 🌐 **Multi-Stack Support**: 34 technology stacks including Next.js, Python, Rust, Go, Java, Angular, Flutter, C++, and more\n- 📊 **Smart Monitoring**: Real-time dashboard with context warnings, heartbeat tracking, and tmux pane titles\n- 🔄 **Auto-Recovery**: Automatically restarts agents when needed with adaptive idle timeout based on work patterns\n- 📈 **Progress Tracking**: Git commits with rich diff summaries and comprehensive HTML run reports\n- 🔄 **Context Management**: Agents automatically clear their own context when nearing limits, plus one-key broadcast of \u002Fclear to all agents (Ctrl+R)\n- ⚙️ **Highly Configurable**: JSON configs with variable substitution and dynamic chunk sizing\n- 🖥️ **Flexible Viewing**: Multiple tmux viewing modes with shell completion support\n- 🔒 **Safe Operation**: Automatic settings backup\u002Frestore with size-based rotation, file locking, atomic operations\n- 🛠️ **Development Setup**: 24 integrated tool installation scripts and pre-flight verification\n- 🎯 **Smart Controls**: Graceful shutdown with force-kill on double Ctrl+C within 3 seconds\n\n## 📋 Prerequisites\n\n- **Python 3.13+** (managed by `uv`)\n- **tmux** (for terminal multiplexing)\n- **Claude Code** (`claude` command installed and configured)\n- **git** (for version control)\n- **Your project's tools** (e.g., `bun` for Next.js, `mypy`\u002F`ruff` for Python)\n- **direnv** (optional but recommended for automatic environment activation)\n- **uv** (modern Python package manager)\n\n### Important: The `cc` Alias\n\nThe agent farm requires a special `cc` alias to launch Claude Code with the necessary permissions:\n\n```bash\nalias cc=\"ENABLE_BACKGROUND_TASKS=1 claude --dangerously-skip-permissions\"\n```\n\nThis alias will be configured automatically by the setup script.\n\n## 🚀 Quick Start\n\n### 1. Clone and Setup\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fclaude_code_agent_farm.git\ncd claude_code_agent_farm\nchmod +x setup.sh\n.\u002Fsetup.sh\n```\n\nThe setup script will:\n- Check and install missing prerequisites\n- Create a Python 3.13 virtual environment\n- Install all dependencies\n- Configure the `cc` alias with automatic detection and fixing of common mis-quotings\n- Validate existing aliases and patch incorrect quote patterns\n- Set up direnv for automatic environment activation\n- Handle both bash and zsh shells automatically\n\n### 2. Verify Your Setup\n\nRun the pre-flight verifier to ensure everything is configured correctly:\n\n```bash\nclaude-code-agent-farm doctor --path \u002Fpath\u002Fto\u002Fproject\n```\n\nThis command checks:\n- Python version compatibility\n- Required tools installation (tmux, git, uv)\n- Claude Code configuration and API keys\n- Project-specific tool availability\n- File permissions and common issues\n\n### 3. Enable Shell Completion (Optional)\n\nFor faster command entry with tab completion:\n\n```bash\n# Auto-detect shell and install completion\nclaude-code-agent-farm install-completion\n\n# Or specify shell explicitly\nclaude-code-agent-farm install-completion --shell bash\nclaude-code-agent-farm install-completion --shell zsh\nclaude-code-agent-farm install-completion --shell fish\n```\n\n### 4. Choose Your Workflow\n\n#### For Bug Fixing (Traditional)\n```bash\n# Next.js project\nclaude-code-agent-farm --path \u002Fpath\u002Fto\u002Fproject --config configs\u002Fnextjs_config.json\n\n# Python project\nclaude-code-agent-farm --path \u002Fpath\u002Fto\u002Fproject --config configs\u002Fpython_config.json\n```\n\n#### For Best Practices Implementation\n```bash\n# Ensure you have a best practices guide in place\ncp best_practices_guides\u002FNEXTJS15_BEST_PRACTICES.md \u002Fpath\u002Fto\u002Fproject\u002Fbest_practices_guides\u002F\n\n# Run with best practices config\nclaude-code-agent-farm --path \u002Fpath\u002Fto\u002Fproject --config configs\u002Fnextjs_best_practices_config.json\n```\n\n## 🛠️ Tool Setup Scripts\n\nThe project includes a comprehensive modular system for setting up development environments:\n\n### Available Setup Scripts\n\nRun the interactive menu:\n```bash\ncd tool_setup_scripts\n.\u002Fsetup.sh\n```\n\nOr run specific setups directly:\n\n1. **Python FastAPI** (`setup_python_fastapi.sh`)\n   - Python 3.12+, uv, ruff, mypy, pre-commit, ipython\n\n2. **Go Web Apps** (`setup_go_webapps.sh`)\n   - Go 1.23+, golangci-lint, air, migrate, mockery, Task, swag\n\n3. **Next.js** (`setup_nextjs.sh`)\n   - Node.js 22+, Bun, pnpm, TypeScript, ESLint, Prettier\n\n4. **SvelteKit\u002FRemix\u002FAstro** (`setup_sveltekit_remix_astro.sh`)\n   - Extends Next.js setup with Vite, Playwright, Vitest, Biome\n\n5. **Rust Development** (`setup_rust.sh`)\n   - Rust toolchain, cargo tools, web & system programming tools\n\n6. **Java Enterprise** (`setup_java_enterprise.sh`)\n   - Java 21 LTS, SDKMAN, Gradle 8.11+, Maven 3.9+, JBang\n\n7. **Bash\u002FZsh Scripting** (`setup_bash_zsh.sh`)\n   - Shell development tools and best practices\n\n8. **Cloud Native DevOps** (`setup_cloud_native_devops.sh`)\n   - Docker, Kubernetes, Terraform, cloud tools\n\n9. **GenAI\u002FLLM Ops** (`setup_genai_llm_ops.sh`)\n   - ML\u002FAI development tools and frameworks\n\n10. **Data Engineering** (`setup_data_engineering.sh`)\n    - Data processing and analytics tools\n\n11. **Serverless Edge** (`setup_serverless_edge.sh`)\n    - Serverless and edge computing tools\n\n12. **Terraform Azure** (`setup_terraform_azure.sh`)\n    - Terraform, Azure CLI, infrastructure tools\n\n13. **Angular** (`setup_angular.sh`)\n    - Node.js, Angular CLI, TypeScript, testing tools\n\n14. **Flutter** (`setup_flutter.sh`)\n    - Flutter SDK, Dart, Android Studio, development tools\n\n15. **React Native** (`setup_react_native.sh`)\n    - React Native CLI, mobile development tools\n\nAdditional setup scripts are available for:\n- **PHP\u002FLaravel** (`setup_php_laravel.sh`)\n- **C++ Systems** (`setup_cpp_systems.sh`)\n- **Solana\u002FAnchor** (`setup_solana_anchor.sh`)\n- **Ansible** (`setup_ansible.sh`)\n- **LLM Dev Testing** (`setup_llm_dev_testing.sh`)\n- **LLM Eval Observability** (`setup_llm_eval_observability.sh`)\n- **Kubernetes AI** (`setup_kubernetes_ai_inference.sh`)\n\n### Setup Features\n\n- 🎨 **Interactive & Safe**: Colorful prompts, always asks before installing\n- 🔍 **Smart Detection**: Checks existing installations to avoid conflicts\n- 🛡️ **Non-Destructive**: Won't overwrite configurations without permission\n- 🐚 **Shell Agnostic**: Works with both bash and zsh\n- 📊 **Progress Tracking**: Shows what's installed and what's pending\n\n## 📖 Understanding the Architecture\n\n### The Two-Script System\n\nThis project consists of two independent scripts that work together:\n\n#### 1. **Python Script** (`claude_code_agent_farm.py`) - The Brain 🧠\n\nThis is the main orchestrator that does all the heavy lifting:\n\n- **Creates and manages tmux sessions** with multiple panes\n- **Generates the problems file** by running configured commands\n- **Launches Claude Code agents** in each tmux pane\n- **Monitors agent health** (context usage, work status, errors)\n- **Auto-restarts agents** when they complete tasks or hit issues\n- **Runs monitoring dashboard** in the tmux controller window\n- **Handles graceful shutdown** with Ctrl+C\n- **Manages settings backup\u002Frestore** to prevent corruption\n- **Implements file locking** for concurrent access safety\n- **Writes monitor state** to JSON file for external monitoring\n\n**You run this script and it stays running** (unless using `--no-monitor` mode). The monitoring dashboard is displayed in the tmux session's controller window, not in the launching terminal.\n\n#### 2. **Shell Script** (`view_agents.sh`) - The Window 🪟\n\nThis is an optional convenience tool for viewing the tmux session:\n\n- **It does NOT interact with the Python script**\n- **Run it in a separate terminal** to peek at agent activity\n- **Provides different viewing modes** (grid, focus, split)\n- **Just a wrapper around tmux commands** for convenience\n- **Automatically suggests font size adjustments** for many agents\n\nThink of it like this:\n- **Python script** = Your car engine (does all the work)\n- **Shell script** = Your dashboard camera (lets you see what's happening)\n\n### Hidden Commands\n\n#### Monitor-Only Mode\nThere's a hidden command for running just the monitor display:\n\n```bash\nclaude-code-agent-farm monitor-only --path \u002Fproject --session claude_agents\n```\n\nThis reads the monitor state file and displays the dashboard without launching agents.\n\n### Why Two Scripts?\n\n1. **Separation of Concerns**: Core logic (Python) vs viewing utilities (shell)\n2. **Flexibility**: You can monitor agents without the viewer script\n3. **Independence**: Either script can be used without the other\n\n## 🎮 Supported Workflows\n\n### 1. Bug Fixing Workflow\n\nAgents work through type-checker and linter problems in parallel:\n- Runs your configured type-check and lint commands\n- Generates a combined problems file\n- Agents select random chunks to fix\n- Marks completed problems to avoid duplication\n- Focuses on fixing existing issues\n- Uses instance-specific seeds for better randomization\n\n### 2. Best Practices Implementation Workflow\n\nAgents systematically implement modern best practices:\n- Reads a comprehensive best practices guide\n- Creates a progress tracking document (`@\u003CSTACK>_BEST_PRACTICES_IMPLEMENTATION_PROGRESS.md`)\n- Implements improvements in manageable chunks\n- Tracks completion percentage for each guideline\n- Maintains continuity between sessions\n- Supports continuing existing work with special prompts\n\n### 3. Cooperating Agents Workflow (Advanced)\n\nThe most sophisticated workflow option transforms the agent farm into a coordinated development team capable of complex, strategic improvements. Amazingly, this powerful feature is implemented entire by means of the prompt file! No actual code is needed to effectuate the system; rather, the LLM (particularly Opus 4) is simply smart enough to understand and reliably implement the system autonomously:\n\n#### Multi-Agent Coordination System\n\nThis workflow implements a distributed coordination protocol that allows multiple agents to work on the same codebase simultaneously without conflicts. The system creates a `\u002Fcoordination\u002F` directory structure in your project:\n\n```\n\u002Fcoordination\u002F\n├── active_work_registry.json     # Central registry of all active work\n├── completed_work_log.json       # Log of completed tasks  \n├── agent_locks\u002F                  # Directory for individual agent locks\n│   └── {agent_id}_{timestamp}.lock\n└── planned_work_queue.json       # Queue of planned but not started work\n```\n\n#### How It Works\n\n1. **Unique Agent Identity**: Each agent generates a unique ID (`agent_{timestamp}_{random_4_chars}`)\n\n2. **Work Claiming Process**: Before starting any work, agents must:\n   - Check the active work registry for conflicts\n   - Create a lock file claiming specific files and features\n   - Register their work plan with detailed scope information\n   - Update their status throughout the work cycle\n\n3. **Conflict Prevention**: The lock file system prevents multiple agents from:\n   - Modifying the same files simultaneously\n   - Implementing overlapping features\n   - Creating merge conflicts or breaking changes\n   - Duplicating completed work\n\n4. **Smart Work Distribution**: Agents automatically:\n   - Select non-conflicting work from available tasks\n   - Queue work if their preferred files are locked\n   - Handle stale locks (>2 hours old) intelligently\n   - Coordinate through descriptive git commits\n\n#### Why This Works Well\n\nThis coordination system solves several critical problems:\n\n- **Eliminates Merge Conflicts**: Lock-based file claiming ensures clean parallel development\n- **Prevents Wasted Work**: Agents check completed work log before starting\n- **Enables Complex Tasks**: Unlike simple bug fixing, agents can tackle strategic improvements\n- **Maintains Code Stability**: Functionality testing requirements prevent breaking changes\n- **Scales Efficiently**: 20+ agents can work productively without stepping on each other\n- **Business Value Focus**: Requires justification and planning before implementation\n\n#### Advanced Features\n\n- **Stale Lock Detection**: Automatically handles abandoned work after 2 hours\n- **Emergency Coordination**: Alert system for critical conflicts\n- **Progress Transparency**: All agents can see what others are working on\n- **Atomic Work Units**: Each agent completes full features before releasing locks\n- **Detailed Planning**: Agents must create comprehensive plans before claiming work\n\n#### Best Use Cases\n\nThis workflow excels at:\n- Large-scale refactoring projects\n- Implementing complex architectural changes\n- Adding comprehensive type hints across a codebase\n- Systematic performance optimizations\n- Multi-faceted security improvements\n- Feature development requiring coordination\n\nTo use this workflow, specify the cooperating agents prompt:\n```bash\nclaude-code-agent-farm \\\n  --path \u002Fproject \\\n  --prompt-file prompts\u002Fcooperating_agents_improvement_prompt_for_python_fastapi_postgres.txt \\\n  --agents 5\n```\n\n## 🌐 Technology Stack Support\n\n### Complete List of 34 Supported Tech Stacks\n\nThe project includes pre-configured support for:\n\n#### Web Development\n1. **Next.js** - TypeScript, React, modern web development\n2. **Angular** - Enterprise Angular applications\n3. **SvelteKit** - Modern web framework\n4. **Remix\u002FAstro** - Full-stack web frameworks\n5. **Flutter** - Cross-platform mobile development\n6. **Laravel** - PHP web framework\n7. **PHP** - General PHP development\n\n#### Systems & Languages\n8. **Python** - FastAPI, Django, data science workflows\n9. **Rust** - System programming and web applications\n10. **Rust CLI** - Command-line tool development\n11. **Go** - Web services and cloud-native applications\n12. **Java** - Enterprise applications with Spring Boot\n13. **C++** - Systems programming and performance-critical applications\n\n#### DevOps & Infrastructure\n14. **Bash\u002FZsh** - Shell scripting and automation\n15. **Terraform\u002FAzure** - Infrastructure as Code\n16. **Cloud Native DevOps** - Kubernetes, Docker, CI\u002FCD\n17. **Ansible** - Infrastructure automation and configuration management\n18. **HashiCorp Vault** - Secrets management and policy as code\n\n#### Data & AI\n19. **GenAI\u002FLLM Ops** - AI\u002FML operations and tooling\n20. **LLM Dev Testing** - LLM development and testing workflows\n21. **LLM Evaluation & Observability** - LLM evaluation and monitoring\n22. **Data Engineering** - ETL, analytics, big data\n23. **Data Lakes** - Kafka, Snowflake, Spark integration\n24. **Polars\u002FDuckDB** - High-performance data processing\n25. **Excel Automation** - Python-based Excel automation with Azure\n26. **PostgreSQL 17 & Python** - Modern PostgreSQL 17 with FastAPI\u002FSQLModel\n\n#### Specialized Domains\n27. **Serverless Edge** - Edge computing and serverless\n28. **Kubernetes AI Inference** - AI inference on Kubernetes\n29. **Security Engineering** - Security best practices and tooling\n30. **Hardware Development** - Embedded systems and hardware design\n31. **Unreal Engine** - Game development with Unreal Engine 5\n32. **Solana\u002FAnchor** - Blockchain development on Solana\n33. **Cosmos** - Cosmos blockchain ecosystem\n34. **React Native** - Cross-platform mobile development\n\nEach stack includes:\n- Optimized configuration file\n- Technology-specific prompts\n- Comprehensive best practices guide (31 guides total)\n- Appropriate chunk sizes and timing\n\n### Custom Tech Stacks\n\nCreate your own configuration:\n\n```json\n{\n  \"comment\": \"Custom Rust configuration\",\n  \"tech_stack\": \"rust\",\n  \"problem_commands\": {\n    \"type_check\": [\"cargo\", \"check\"],\n    \"lint\": [\"cargo\", \"clippy\", \"--\", \"-D\", \"warnings\"]\n  },\n  \"best_practices_files\": [\".\u002Fguides\u002FRUST_BEST_PRACTICES.md\"],\n  \"chunk_size\": 30,\n  \"prompt_file\": \"prompts\u002Frust_prompt.txt\",\n  \"agents\": 15,\n  \"max_agents\": 50,\n  \"auto_restart\": true,\n  \"git_branch\": \"feature\u002Frust-improvements\",\n  \"git_remote\": \"origin\"\n}\n```\n\n## ⚙️ Configuration System\n\n### Core Configuration Options\n\n```json\n{\n  \"comment\": \"Human-readable description\",\n  \"tech_stack\": \"nextjs\",\n  \"problem_commands\": {\n    \"type_check\": [\"bun\", \"run\", \"type-check\"],\n    \"lint\": [\"bun\", \"run\", \"lint\"],\n    \"test\": [\"bun\", \"run\", \"test\"]\n  },\n  \"best_practices_files\": [\".\u002Fbest_practices_guides\u002FNEXTJS15_BEST_PRACTICES.md\"],\n  \"chunk_size\": 50,\n  \"agents\": 20,\n  \"max_agents\": 50,\n  \"session\": \"claude_agents\",\n  \"prompt_file\": \"prompts\u002Fdefault_prompt_nextjs.txt\",\n  \"auto_restart\": true,\n  \"context_threshold\": 20,\n  \"idle_timeout\": 60,\n  \"max_errors\": 3,\n  \"git_branch\": null,\n  \"git_remote\": \"origin\",\n  \"tmux_kill_on_exit\": true,\n  \"tmux_mouse\": true,\n  \"stagger\": 10.0,\n  \"wait_after_cc\": 15.0,\n  \"check_interval\": 10,\n  \"skip_regenerate\": false,\n  \"skip_commit\": false,\n  \"no_monitor\": false,\n  \"attach\": false,\n  \"fast_start\": false,\n  \"full_backup\": false\n}\n```\n\n### Key Parameters\n\n- **tech_stack**: Technology identifier (one of 34 supported stacks)\n- **problem_commands**: Commands for type-checking, linting, and testing\n- **best_practices_files**: Guides to copy to the project\n- **chunk_size**: Base lines\u002Fchanges per agent iteration (dynamically adjusted based on remaining work)\n- **prompt_file**: Which prompt template to use (36 available)\n- **agents**: Number of agents to run (default: 20)\n- **max_agents**: Maximum allowed agents (default: 50)\n- **auto_restart**: Enable automatic agent restart\n- **context_threshold**: Auto-clear context when it drops below this %\n- **git_branch**: Optional specific branch to commit to\n- **git_remote**: Remote to push to (default: origin)\n\n### Command Line Options\n\nAll configuration options can be overridden via CLI:\n\n```bash\nclaude-code-agent-farm \\\n  --path \u002Fproject \\\n  --config configs\u002Fbase.json \\\n  --agents 10 \\\n  --chunk-size 30 \\\n  --auto-restart\n```\n\n#### Complete Options Reference\n\n```\nCommands:\n  doctor                   Run pre-flight verification checks\n  monitor-only             Display monitor dashboard (internal use)\n\nRequired:\n  --path PATH               Project root directory\n\nAgent Configuration:\n  --agents N, -n N         Number of agents (default: 20)\n  --session NAME, -s NAME  tmux session name (default: claude_agents)\n  --chunk-size N           Override config chunk size\n\nTiming:\n  --stagger SECONDS        Delay between starting agents (default: 10.0)\n  --wait-after-cc SECONDS  Wait time after launching cc (default: 15.0)\n  --check-interval SECONDS Health check interval (default: 10)\n\nFeatures:\n  --skip-regenerate        Skip regenerating problems file\n  --skip-commit           Skip git commit\u002Fpush\n  --auto-restart          Enable automatic agent restart\n  --no-monitor            Just launch agents and exit\n  --attach                Attach to tmux after setup\n\nAdvanced:\n  --prompt-file PATH      Custom prompt file\n  --config PATH           JSON configuration file\n  --context-threshold N    Auto-clear context when context ≤ N% (default: 20)\n  --idle-timeout SECONDS   Mark agent idle after N seconds (default: 60)\n  --max-errors N           Disable agent after N errors (default: 3)\n  --commit-every N         Commit after every N regeneration cycles\n  --tmux-kill-on-exit      Kill tmux session on exit (default: true)\n  --no-tmux-kill-on-exit   Keep tmux session running after exit\n  --tmux-mouse             Enable tmux mouse support (default: true)\n  --no-tmux-mouse          Disable tmux mouse support\n  --fast-start             Skip shell prompt detection\n  --full-backup            Full backup of Claude settings before start\n```\n\n## 📝 Prompt System\n\n### Complete Prompt Inventory (37 Prompts)\n\nThe system includes specialized prompts for all workflows and tech stacks:\n\n#### Bug Fixing Prompts (4)\n- `default_prompt.txt` - Generic bug fixing\n- `default_prompt_nextjs.txt` - Next.js specific\n- `default_prompt_python.txt` - Python specific\n- `bug_fixing_prompt_for_nextjs.txt` - Advanced Next.js fixing\n\n#### Cooperating Agents Prompts (1)\n- `cooperating_agents_improvement_prompt_for_python_fastapi_postgres.txt` - Multi-agent coordination system\n\n#### Best Practices Implementation Prompts (31)\n- `default_best_practices_prompt.txt` - Generic implementation\n- `continue_best_practices_prompt.txt` - Continue existing work\n\n##### Web Development (7)\n- `default_best_practices_prompt_nextjs.txt` - Next.js 15\n- `default_best_practices_prompt_angular.txt` - Angular\n- `default_best_practices_prompt_sveltekit.txt` - SvelteKit\n- `default_best_practices_prompt_remix_astro.txt` - Remix\u002FAstro\n- `default_best_practices_prompt_flutter.txt` - Flutter\n- `default_best_practices_prompt_laravel.txt` - Laravel\n- `default_best_practices_prompt_php.txt` - PHP\n\n##### Systems & Languages (7)\n- `default_best_practices_prompt_python.txt` - Python\u002FFastAPI\n- `default_best_practices_prompt_rust_web.txt` - Rust web apps\n- `default_best_practices_prompt_rust_system.txt` - Rust systems\n- `default_best_practices_prompt_rust_cli.txt` - Rust CLI tools\n- `default_best_practices_prompt_go.txt` - Go applications\n- `default_best_practices_prompt_java.txt` - Java enterprise\n- `default_best_practices_prompt_cpp.txt` - C++ systems\n\n##### DevOps & Infrastructure (5)\n- `default_best_practices_prompt_bash_zsh.txt` - Shell scripting\n- `default_best_practices_prompt_terraform_azure.txt` - IaC\n- `default_best_practices_prompt_cloud_native_devops.txt` - DevOps\n- `default_best_practices_prompt_ansible.txt` - Ansible automation\n- `default_best_practices_prompt_vault.txt` - HashiCorp Vault\n\n##### Data & AI (7)\n- `default_best_practices_prompt_genai_llm_ops.txt` - AI\u002FML ops\n- `default_best_practices_prompt_llm_dev_testing.txt` - LLM development\n- `default_best_practices_prompt_llm_eval_observability.txt` - LLM evaluation\n- `default_best_practices_prompt_data_engineering.txt` - Data pipelines\n- `default_best_practices_prompt_data_lakes.txt` - Data lakes\n- `default_best_practices_prompt_polars.txt` - Polars\u002FDuckDB\n- `default_best_practices_prompt_excel.txt` - Excel automation\n\n##### Specialized (7)\n- `default_best_practices_prompt_serverless_edge.txt` - Edge computing\n- `default_best_practices_prompt_kubernetes_ai.txt` - Kubernetes AI\n- `default_best_practices_prompt_security.txt` - Security engineering\n- `default_best_practices_prompt_hardware.txt` - Hardware development\n- `default_best_practices_prompt_unreal.txt` - Unreal Engine\n- `default_best_practices_prompt_solana.txt` - Solana blockchain\n- `default_best_practices_prompt_cosmos.txt` - Cosmos blockchain\n- `default_best_practices_prompt_react_native.txt` - React Native\n\n### Variable Substitution\n\nPrompts support dynamic variables:\n- `{chunk_size}` - Replaced with configured chunk size\n\nExample in prompt:\n```\nWork on approximately {chunk_size} improvements at a time...\n```\n\n## 🔄 How It Works\n\n### Bug Fixing Workflow\n\n1. **Problem Generation**: Runs type-check, lint, and test commands\n2. **Agent Launch**: Starts N agents in tmux panes\n3. **Task Distribution**: Each agent selects random problem chunks\n4. **Conflict Prevention**: Marks completed problems with [COMPLETED]\n5. **Progress Tracking**: Commits changes with rich diff summaries showing file counts and change statistics\n\n### Best Practices Workflow\n\n1. **Guide Distribution**: Copies best practices guides to project\n2. **Progress Document**: Agents create\u002Fupdate tracking document\n3. **Systematic Implementation**: Works through guidelines incrementally\n4. **Accurate Tracking**: Maintains honest completion percentages\n5. **Session Continuity**: Progress persists between runs\n\n### Safety Features\n\n1. **Settings Backup**: Automatically backs up Claude settings before starting\n   - Creates timestamped backups in `.claude_agent_farm_backups\u002F` in your project\n   - Keeps last 10 backups with automatic rotation\n   - Enforces 200MB total size limit to prevent disk bloat\n   - Full backup option with `--full-backup` flag\n   - Reports backup storage status after cleanup\n2. **Settings Restore**: Restores from backup if corruption detected\n   - Automatic detection of settings errors\n   - Seamless restoration during agent startup\n3. **File Locking**: Uses file locks to prevent concurrent access issues\n   - Lock files in `~\u002F.claude\u002F.agent_farm_launch.lock`\n   - 30-second stale lock detection and cleanup\n   - Prevents concurrent Claude launches that could corrupt settings\n4. **Permission Management**: Automatically fixes file permissions\n   - Sets 600 permissions on settings.json\n   - Sets 700 permissions on .claude directory\n   - Ensures proper file ownership\n5. **Atomic Operations**: Uses atomic file operations for safety\n6. **Emergency Cleanup**: Handles unexpected exits gracefully\n   - Cleans up tmux sessions\n   - Removes lock files\n   - Deletes state files\n7. **Launch Locking**: Prevents concurrent Claude launches with lock files\n8. **Adaptive Stagger**: Intelligent launch delays based on success\u002Ffailure\n   - Halves stagger time when previous launch succeeds (faster startup when healthy)\n   - Doubles stagger time only when previous launch fails (retains safety)\n   - Capped at 60 seconds maximum to prevent excessive delays\n9. **Agent Limits**: Enforces max_agents limit (default: 50)\n10. **Instance Randomization**: Adds unique seeds to each agent for better work distribution\n\n## 📊 Monitoring Dashboard\n\nThe Python script includes a real-time monitoring dashboard that shows:\n\n- **Agent Status**: Working, Idle, Context Low, Error, Disabled\n- **Context Usage**: Percentage of agent's context window used with visual warnings\n- **Heartbeat Age**: Time since last agent activity pulse (color-coded)\n- **Last Activity**: Time since the agent last did something\n- **Last Error**: Most recent error message (if any)\n- **Session Stats**: Total restarts, uptime, active agents\n- **Cycle Count**: Number of work cycles completed\n\n### Context Warnings\n\nEach tmux pane displays context warnings in its title bar:\n- ⚠️ **Critical** (≤20%): Agent will clear context soon\n- ⚡ **Low** (≤30%): Context running low\n- Normal percentage display for healthy levels\n\n### Built-in Dashboard\n\nThe monitoring dashboard runs in the tmux controller window:\n\n```\nClaude Agent Farm - 14:32:15\n┏━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┓\n┃ Agent    ┃ Status     ┃ Cycles ┃ Context  ┃ Runtime      ┃ Heartbeat┃ Errors ┃\n┡━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━┩\n│ Pane 00  │ working    │ 2      │ 75%      │ 0:05:23      │ 12s      │ 0      │\n│ Pane 01  │ working    │ 2      │ 82%      │ 0:05:19      │ 8s       │ 0      │\n│ Pane 02  │ idle       │ 3      │ 45%      │ 0:05:15      │ 45s      │ 0      │\n└──────────┴────────────┴────────┴──────────┴──────────────┴──────────┴────────┘\n```\n\n### Viewing Options\n\n```bash\n# Use the viewer script\n.\u002Fview_agents.sh\n\n# Direct tmux commands\ntmux attach -t claude_agents\ntmux attach -t claude_agents:controller  # Dashboard only\n```\n\n### Context Reset Macro\n\nPress `Ctrl+R` from any tmux window to broadcast the `\u002Fclear` command to all agents simultaneously. This frees up context across all agents with a single keystroke, useful when multiple agents are running low on context.\n\n### Agent States\n\n- 🟡 **starting** - Agent initializing\n- 🟢 **working** - Actively processing\n- 🔵 **ready** - Waiting for input\n- 🟡 **idle** - Completed work\n- 🔴 **error** - Problem detected\n- ⚫ **unknown** - State unclear\n\n### Auto-Restart Features\n\nWhen `--auto-restart` is enabled:\n- Monitors agent health continuously via heartbeat files\n- Restarts agents that hit errors, go idle, or have stale heartbeats (>2 minutes)\n- Monitors context percentage and clears context when below threshold\n- Adaptive idle timeout adjusts based on agent work patterns\n  - Tracks cycle completion times across all agents\n  - Sets timeout to 3× median cycle time (bounded 30s-600s)\n  - Prevents false positives on complex tasks\n  - Speeds up detection on simple tasks\n- Implements exponential backoff to prevent restart loops\n  - Initial wait: 10 seconds\n  - Doubles with each restart (max 5 minutes)\n- Tracks restart count per agent\n- Disables agents after max_errors threshold\n\n### Monitor State File\n\nThe system writes monitor state to `.claude_agent_farm_state.json` in the project directory. This file contains:\n- Agent statuses and health metrics\n- Session information\n- Runtime statistics\n\nStructure:\n```json\n{\n  \"session\": \"claude_agents\",\n  \"num_agents\": 20,\n  \"agents\": {\n    \"0\": {\n      \"status\": \"working\",\n      \"start_time\": \"2024-01-15T10:30:00\",\n      \"last_activity\": \"2024-01-15T10:35:00\",\n      \"last_restart\": null,\n      \"cycles\": 2,\n      \"last_context\": 75,\n      \"errors\": 0,\n      \"restart_count\": 0\n    }\n  },\n  \"start_time\": \"2024-01-15T10:30:00\",\n  \"timestamp\": \"2024-01-15T10:35:00\"\n}\n```\n\nExternal tools can read this file to monitor the farm's progress.\n\n### HTML Run Reports\n\nAt the end of each run, the system generates a comprehensive HTML report with:\n\n- **Run Summary**: Duration, agents used, problems fixed, commits made\n- **Agent Performance**: Individual agent statistics including cycles, context usage, errors, and restarts\n- **Configuration Details**: All settings used for the run\n- **Visual Formatting**: Rich HTML output with syntax highlighting and dark theme\n\nReports are saved as `agent_farm_report_YYYYMMDD_HHMMSS.html` in the project directory.\n\nFeatures:\n- Single-file HTML with inline styles (no external dependencies)\n- Professional dark theme optimized for code review\n- Sortable tables with color-coded status indicators\n- Complete run statistics for documentation or pull requests\n- Automatic generation on graceful shutdown\n\n## 💡 Usage Examples\n\n### Quick Test Run\n```bash\n# 5 agents, skip git operations\nclaude-code-agent-farm --path \u002Fproject -n 5 --skip-regenerate --skip-commit\n```\n\n### Production Bug Fixing\n```bash\n# Full run with Python project\nclaude-code-agent-farm \\\n  --path \u002Fpython\u002Fproject \\\n  --config configs\u002Fpython_uv_config.json \\\n  --agents 15 \\\n  --auto-restart\n```\n\n### Best Practices Implementation\n```bash\n# Systematic improvements\nclaude-code-agent-farm \\\n  --path \u002Fnextjs\u002Fproject \\\n  --config configs\u002Fnextjs_best_practices_config.json \\\n  --agents 10\n```\n\n### Incremental Commits\n```bash\n# Commit progress every 5 cycles\nclaude-code-agent-farm \\\n  --path \u002Fproject \\\n  --config configs\u002Fpython_config.json \\\n  --agents 20 \\\n  --commit-every 5 \\\n  --auto-restart\n```\n\n### Custom Configuration\n```bash\n# Override config settings\nclaude-code-agent-farm \\\n  --path \u002Fproject \\\n  --config configs\u002Fbase.json \\\n  --chunk-size 25 \\\n  --context-threshold 15 \\\n  --idle-timeout 120\n```\n\n### Headless Operation\n```bash\n# Run without monitoring (for CI\u002FCD)\nclaude-code-agent-farm \\\n  --path \u002Fproject \\\n  --config configs\u002Fci-config.json \\\n  --no-monitor \\\n  --auto-restart\n```\n\n### Specialized Stacks\n```bash\n# Angular development\nclaude-code-agent-farm \\\n  --path \u002Fangular\u002Fproject \\\n  --config configs\u002Fangular_config.json\n\n# Blockchain development\nclaude-code-agent-farm \\\n  --path \u002Fsolana\u002Fproject \\\n  --config configs\u002Fsolana_anchor_config.json\n\n# Data engineering\nclaude-code-agent-farm \\\n  --path \u002Fdata\u002Fproject \\\n  --config configs\u002Fpolars_duckdb_config.json\n```\n\n### Cooperating Agents Mode\n```bash\n# Advanced multi-agent coordination for complex improvements\nclaude-code-agent-farm \\\n  --path \u002Fproject \\\n  --prompt-file prompts\u002Fcooperating_agents_improvement_prompt_for_python_fastapi_postgres.txt \\\n  --agents 20 \\\n  --auto-restart\n```\n\n## 🚨 Troubleshooting\n\n### Common Issues\n\n#### Agents not starting\n- Verify `cc` alias: `alias | grep cc`\n- Test Claude Code manually: `cc`\n- Check API key configuration\n- Increase `--wait-after-cc` timing\n- Use `--full-backup` flag if settings corruption suspected\n\n#### Configuration errors\n- Validate JSON syntax\n- Ensure all paths are correct\n- Check command availability (mypy, ruff, etc.)\n- Verify best practices guides exist\n\n#### Resource issues\n- Each agent uses ~500MB RAM\n- Reduce agent count if needed\n- Monitor with `htop`\n- Check available disk space for logs\n- Respect max_agents limit (default: 50)\n\n#### Settings corruption\n- System automatically backs up settings\n- Restores from backup on error detection\n- Manual restore: Check `~\u002F.claude\u002Fbackups\u002F`\n- Use `--full-backup` for comprehensive backup\n\n### Debug Features\n\n- **State File**: Check `.claude_agent_farm_state.json` for agent status\n- **Heartbeat Files**: Monitor `.heartbeats\u002Fagent*.heartbeat` for activity tracking\n- **Lock Files**: Look for `.agent_farm_launch.lock` in `~\u002F.claude\u002F`\n- **Backup Directory**: `.claude_agent_farm_backups\u002F` in project contains settings backups\n- **Pre-flight Check**: Run `claude-code-agent-farm doctor` to diagnose issues\n- **Emergency Cleanup**: Ctrl+C triggers graceful shutdown\n  - First Ctrl+C: Graceful shutdown with agent cleanup\n  - Second Ctrl+C within 3 seconds: Force kills tmux session\n  - Automatically cleans up state files and locks\n- **Manual tmux**: `tmux kill-session -t claude_agents` to force cleanup\n\n## 📁 Project Structure\n\n```\nclaude_code_agent_farm\u002F\n├── claude_code_agent_farm.py    # Main orchestrator\n├── view_agents.sh               # Tmux viewer utility\n├── setup.sh                     # Automated setup\n├── pyproject.toml              # Python project configuration\n├── uv.lock                     # Locked dependencies\n├── .envrc                      # direnv configuration\n├── .gitignore                  # Git ignore patterns\n├── configs\u002F                     # 33 configuration files\n│   ├── nextjs_config.json      # Next.js bug fixing\n│   ├── python_config.json      # Python bug fixing\n│   ├── python_uv_config.json   # Python with uv\n│   ├── nextjs_best_practices_config.json\n│   ├── angular_config.json     # Angular development\n│   ├── flutter_config.json     # Flutter mobile\n│   ├── rust_system_config.json # Rust systems programming\n│   ├── rust_webapps_config.json # Rust web apps\n│   ├── rust_cli_config.json    # Rust CLI tools\n│   ├── go_webapps_config.json  # Go web development\n│   ├── java_enterprise_config.json # Java enterprise\n│   ├── cpp_systems_config.json # C++ systems\n│   ├── php_config.json         # PHP development\n│   ├── laravel_config.json     # Laravel framework\n│   ├── sveltekit2_config.json  # SvelteKit framework\n│   ├── remix_astro_config.json # Remix\u002FAstro frameworks\n│   ├── bash_zsh_config.json    # Shell scripting\n│   ├── terraform_azure_config.json # Infrastructure as Code\n│   ├── cloud_native_devops_config.json # DevOps tools\n│   ├── ansible_config.json     # Ansible automation\n│   ├── vault_config.json       # HashiCorp Vault\n│   ├── genai_llm_ops_config.json # AI\u002FML operations\n│   ├── data_engineering_config.json # Data pipelines\n│   ├── data_lakes_config.json  # Kafka\u002FSnowflake\u002FSpark\n│   ├── polars_duckdb_config.json # Data processing\n│   ├── excel_automation_config.json # Excel automation\n│   ├── serverless_edge_config.json # Edge computing\n│   ├── security_engineering_config.json # Security\n│   ├── hardware_dev_config.json # Hardware development\n│   ├── unreal_engine_config.json # Game development\n│   ├── solana_anchor_config.json # Solana blockchain\n│   ├── cosmos_blockchain_config.json # Cosmos blockchain\n│   └── sample.json             # Example configuration\n├── prompts\u002F                     # 37 prompt templates\n│   ├── Bug fixing prompts (4)\n│   ├── Cooperating agents prompts (1)\n│   ├── Generic best practices prompts (2)\n│   └── Stack-specific best practices prompts (30)\n├── best_practices_guides\u002F       # 35 best practices documents\n│   ├── Web Development (7 guides)\n│   ├── Systems & Languages (7 guides)\n│   ├── DevOps & Infrastructure (5 guides)\n│   ├── Data & AI (6 guides)\n│   └── Specialized Domains (6 guides)\n├── tool_setup_scripts\u002F          # 24 development environment setup scripts\n│   ├── setup.sh                # Interactive menu\n│   ├── common_utils.sh         # Shared utilities\n│   ├── README.md              # Setup scripts documentation\n│   ├── Web Development (4 scripts)\n│   ├── Systems & Languages (3 scripts)\n│   ├── DevOps & Infrastructure (3 scripts)\n│   └── Data & AI (3 scripts)\n└── __pycache__\u002F                # Python cache (gitignored)\n```\n\n## 🔧 Advanced Topics\n\n### Creating Custom Workflows\n\n1. **Define your tech stack config** (see 34 examples)\n2. **Create appropriate prompts** (follow 37 existing patterns)\n3. **Add best practices guides** (optional, see 35 examples)\n4. **Configure problem commands** (type-check, lint, test)\n5. **Set appropriate chunk sizes** (20-75 based on complexity)\n6. **Test with small agent counts first**\n\n### Scaling Considerations\n\n- Start small (5-10 agents) and scale up\n- Maximum 50 agents by default (configurable via `max_agents`)\n- Increase stagger time for many agents\n- Consider running in batches for 50+ agents\n- Use `--no-monitor` for headless operation\n- Monitor system resources (RAM, CPU)\n- Adjust chunk sizes based on performance\n\n### Integration with CI\u002FCD\n\n```bash\n#!\u002Fbin\u002Fbash\n# Automated code improvement script\nclaude-code-agent-farm \\\n  --path $PROJECT_PATH \\\n  --config configs\u002Fci-config.json \\\n  --no-monitor \\\n  --auto-restart \\\n  --skip-commit \\\n  --agents 10\n```\n\n### Custom Git Workflows\n\nConfigure custom git branches and remotes in your config:\n\n```json\n{\n  \"git_branch\": \"feature\u002Fai-improvements\",\n  \"git_remote\": \"upstream\",\n  \"skip_commit\": false\n}\n```\n\n### Performance Tuning\n\n- **Chunk Size**: Automatically adjusts based on remaining work\n  - Base sizes by stack: Python (50), Next.js (50), Rust (30), Go (40), Java (35)\n  - Dynamic formula: `max(10, total_lines \u002F agents \u002F 2)`\n  - Prevents agents from running out of work or doing trivial tasks\n- **Stagger Time**: Adaptive timing based on launch success\n  - Default 10s baseline prevents settings corruption\n  - Automatically halves when previous launch succeeds (minimum: baseline)\n  - Doubles only when previous launch fails (maximum: 60s)\n  - Results in faster startup when system is healthy\n- **Context Threshold**: Lower values (15-20%) clear context sooner\n- **Idle Timeout**: Adjust based on task complexity\n- **Check Interval**: Balance between responsiveness and CPU usage\n- **Heartbeat Monitoring**: Detects stuck agents (>2 minutes since last pulse)\n- **Max Agents**: Increase beyond 50 for powerful systems\n- **Wait After CC**: Default 15s ensures Claude is fully ready\n  - Increase if seeing startup failures\n- **Incremental Commits**: Use `--commit-every N` to commit progress periodically\n  - Prevents giant diffs that are hard to review\n  - Tracks minimum cycles across all agents for consistency\n\n### Advanced Features\n\n#### Interruptible Operations\n- All long-running operations can be interrupted with Ctrl+C\n- Graceful shutdown preserves work in progress\n- Emergency cleanup on unexpected exits\n\n#### Smart Error Detection\n- Detects multiple error conditions:\n  - Settings corruption\n  - Authentication failures  \n  - Welcome\u002Fsetup screens\n  - Command not found errors\n  - Parse errors (TypeError, SyntaxError, JSONDecodeError)\n  - Login prompts and API key issues\n- Automatic recovery attempts before disabling agents\n- Preserves other working agents during recovery\n\n#### Variable Substitution in Prompts\n- `{chunk_size}` - Replaced with configured chunk size\n- Supports regex patterns for flexible prompt templates\n\n#### Session Name Validation\n- Only allows letters, numbers, hyphens, and underscores\n- Prevents tmux errors from invalid characters\n\n#### Shell Prompt Detection\n- Intelligently waits for shell prompts before sending commands\n- `--fast-start` flag skips prompt detection for faster launches\n- Handles both bash and zsh prompts\n- Robust, multi-layer readiness check before sending commands:\n  1. Passive heuristics that recognise common prompt symbols and current directory names\n  2. Active probe fallback that sends a one-off `echo` with a unique marker and waits for the response – works even with minimal or heavily customised prompts\n  Works seamlessly with bash, zsh, fish, and other POSIX-compatible shells\n  `--fast-start` flag remains available to skip detection entirely for advanced users who want the quickest possible launch\n\n#### User Confirmations\n- Interruptible confirmation prompts (Ctrl+C uses default)\n- Safe defaults for all destructive operations\n- Clear messaging for all user interactions\n\n## 🤝 Contributing\n\nContributions welcome! Please:\n1. Fork the repository\n2. Create a feature branch\n3. Add tests if applicable\n4. Update documentation\n5. Submit a pull request\n\n### Adding New Tech Stacks\n\n1. Create config file in `configs\u002F` (34 examples to follow)\n2. Add prompts in `prompts\u002F` (37 examples available)\n3. Write best practices guide in `best_practices_guides\u002F` (35 examples)\n4. Add setup script in `tool_setup_scripts\u002F` (15 examples)\n5. Test thoroughly with various project types\n6. Update this README with your addition\n\n## 👨‍💻 Author\n\nCreated by Jeffrey Emanuel (jeffrey.emanuel@gmail.com)\n\n## 📄 License\n\nMIT License (with OpenAI\u002FAnthropic Rider) — see [LICENSE](LICENSE) file\n\n## ⚠️ Important Notes\n\n- **Always backup your code** before running\n- **Review changes** before committing\n- **Start with few agents** to test\n- **Monitor first runs** to ensure proper behavior\n- **Check resource usage** for large agent counts\n- **Verify cc alias** is properly configured\n- **Ensure git is configured** with proper credentials\n- **Respect agent limits** (default max: 50)\n- **Claude settings** are automatically backed up and restored\n- **Lock files** prevent concurrent launches and corruption\n- **State files** enable external monitoring tools\n\n## 🔍 Additional Resources\n\n### Monitoring Tools\n- Monitor state file (`.claude_agent_farm_state.json`) for external integrations\n- Heartbeat files (`.heartbeats\u002Fagent*.heartbeat`) track agent activity\n- tmux pane titles show real-time context warnings\n- tmux session logs for debugging agent issues\n- Git commit history for tracking improvements\n\n### Recovery Options\n- Manual settings restore from `.claude_agent_farm_backups\u002F` in your project\n- Lock file cleanup: `rm ~\u002F.claude\u002F.agent_farm_launch.lock`\n- Emergency session cleanup: `tmux kill-session -t claude_agents`\n- View HTML run reports from previous sessions for debugging\n\n### Performance Optimization\n- Use SSDs for better file I\u002FO performance\n- Allocate 500MB RAM per agent\n- Consider network bandwidth for API calls\n- Monitor CPU usage with `htop` during runs\n\n---\n\n*Happy farming! 🚜 May your code be clean and your agents productive.*\n\n## 📊 Quick Reference\n\n### Tech Stack Support Summary\n\n| Category | Count | Examples |\n|----------|-------|----------|\n| Web Development | 8 | Next.js, Angular, Flutter, Laravel, React Native |\n| Systems & Languages | 7 | Python, Rust, Go, Java, C++ |\n| DevOps & Infrastructure | 6 | Terraform, Kubernetes, Ansible |\n| Data & AI | 8 | GenAI\u002FLLM, Data Lakes, PostgreSQL 17, Polars |\n| Specialized | 5 | Security, Hardware, Blockchain |\n| **Total** | **34** | |\n\n### Resource Summary\n\n| Resource | Count |\n|----------|-------|\n| Configuration Files | 37 |\n| Prompt Templates | 37 |\n| Best Practices Guides | 35 |\n| Tool Setup Scripts | 24 |","# Claude 代码智能体农场 🤖🚜\n\n> 协调多个 Claude 代码智能体并行工作，通过自动化修复 bug 或系统化实施最佳实践来优化您的代码库\n\n[![Python 3.13+](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.13+-blue.svg)](https:\u002F\u002Fwww.python.org\u002Fdownloads\u002F)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT%2BOpenAI%2FAnthropic%20Rider-blue.svg)](.\u002FLICENSE)\n[![Code style: ruff](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fcode%20style-ruff-000000.svg)](https:\u002F\u002Fgithub.com\u002Fastral-sh\u002Fruff)\n\n## 🎯 这是什么？\n\nClaude 代码智能体农场是一个强大的编排框架，可并行运行多个 Claude 代码 (`cc`) 会话，以系统化地改进您的代码库。它支持多种技术栈和工作流类型，允许 AI 智能体团队协同完成大规模的代码优化任务。\n\n### 核心特性\n\n- 🚀 **并行处理**：可同时运行 20 多个 Claude 代码智能体（使用 `max_agents` 配置最高可达 50 个）\n- 🎯 **多工作流支持**：包括 bug 修复、最佳实践实施，或协调一致的多智能体开发\n- 🤝 **智能体协作**：先进的锁机制防止并行智能体之间的冲突\n- 🌐 **多技术栈支持**：涵盖 34 种技术栈，包括 Next.js、Python、Rust、Go、Java、Angular、Flutter、C++ 等\n- 📊 **智能监控**：实时仪表板显示上下文警告、心跳状态跟踪及 tmux 窗格标题\n- 🔄 **自动恢复**：根据工作模式自适应空闲超时，必要时自动重启智能体\n- 📈 **进度追踪**：生成带有丰富差异摘要的 Git 提交，并提供全面的 HTML 运行报告\n- 🔄 **上下文管理**：智能体在接近限制时自动清理自身上下文；同时支持一键向所有智能体广播 `\u002Fclear` 命令（Ctrl+R）\n- ⚙️ **高度可配置**：基于 JSON 的配置文件，支持变量替换与动态分块大小调整\n- 🖥️ **灵活查看**：多种 tmux 查看模式，并支持 Shell 自动补全\n- 🔒 **安全运行**：自动进行设置备份与恢复，结合按大小轮转、文件锁定及原子操作确保安全性\n- 🛠️ **开发环境搭建**：集成 24 个工具安装脚本及预检验证功能\n- 🎯 **智能控制**：优雅关闭程序，若在 3 秒内连续两次按下 Ctrl+C，则强制终止进程\n\n## 📋 先决条件\n\n- **Python 3.13+**（由 `uv` 管理）\n- **tmux**（用于终端多路复用）\n- **Claude 代码**（已安装并配置 `claude` 命令）\n- **git**（用于版本控制）\n- **项目所需工具**（如 Next.js 使用 `bun`，Python 使用 `mypy`\u002F`ruff` 等）\n- **direnv**（可选但推荐，用于自动激活环境）\n- **uv**（现代 Python 包管理器）\n\n### 重要提示：`cc` 别名\n\n智能体农场需要一个特殊的 `cc` 别名，以便以必要的权限启动 Claude 代码：\n\n```bash\nalias cc=\"ENABLE_BACKGROUND_TASKS=1 claude --dangerously-skip-permissions\"\n```\n\n此别名将由安装脚本自动配置。\n\n## 🚀 快速开始\n\n### 1. 克隆并设置\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fclaude_code_agent_farm.git\ncd claude_code_agent_farm\nchmod +x setup.sh\n.\u002Fsetup.sh\n```\n\n安装脚本将执行以下操作：\n- 检查并安装缺失的先决条件\n- 创建 Python 3.13 虚拟环境\n- 安装所有依赖项\n- 配置 `cc` 别名，自动检测并修正常见引号错误\n- 验证现有别名，并修复不正确的引号模式\n- 设置 direnv 以实现环境的自动激活\n- 自动适配 bash 和 zsh shell\n\n### 2. 验证设置\n\n运行预检验证程序，确保所有配置正确无误：\n\n```bash\nclaude-code-agent-farm doctor --path \u002Fpath\u002Fto\u002Fproject\n```\n\n该命令将检查：\n- Python 版本兼容性\n- 必要工具是否已安装（tmux、git、uv）\n- Claude 代码配置及 API 密钥\n- 项目特定工具的可用性\n- 文件权限及其他常见问题\n\n### 3. 启用 Shell 补全（可选）\n\n若需更快地输入命令并享受 Tab 补全功能：\n\n```bash\n# 自动检测 Shell 并安装补全\nclaude-code-agent-farm install-completion\n\n# 或者手动指定 Shell\nclaude-code-agent-farm install-completion --shell bash\nclaude-code-agent-farm install-completion --shell zsh\nclaude-code-agent-farm install-completion --shell fish\n```\n\n### 4. 选择您的工作流\n\n#### 用于传统 Bug 修复\n```bash\n# Next.js 项目\nclaude-code-agent-farm --path \u002Fpath\u002Fto\u002Fproject --config configs\u002Fnextjs_config.json\n\n# Python 项目\nclaude-code-agent-farm --path \u002Fpath\u002Fto\u002Fproject --config configs\u002Fpython_config.json\n```\n\n#### 用于最佳实践实施\n```bash\n# 确保您已准备好最佳实践指南\ncp best_practices_guides\u002FNEXTJS15_BEST_PRACTICES.md \u002Fpath\u002Fto\u002Fproject\u002Fbest_practices_guides\u002F\n\n# 使用最佳实践配置运行\nclaude-code-agent-farm --path \u002Fpath\u002Fto\u002Fproject --config configs\u002Fnextjs_best_practices_config.json\n```\n\n## 🛠️ 工具安装脚本\n\n该项目包含一套全面的模块化系统，用于快速搭建开发环境：\n\n### 可用的设置脚本\n\n运行交互式菜单：\n```bash\ncd tool_setup_scripts\n.\u002Fsetup.sh\n```\n\n或者直接运行特定的设置脚本：\n\n1. **Python FastAPI** (`setup_python_fastapi.sh`)\n   - Python 3.12+、uv、ruff、mypy、pre-commit、ipython\n\n2. **Go Web 应用** (`setup_go_webapps.sh`)\n   - Go 1.23+、golangci-lint、air、migrate、mockery、Task、swag\n\n3. **Next.js** (`setup_nextjs.sh`)\n   - Node.js 22+、Bun、pnpm、TypeScript、ESLint、Prettier\n\n4. **SvelteKit\u002FRemix\u002FAstro** (`setup_sveltekit_remix_astro.sh`)\n   - 基于 Next.js 设置，扩展了 Vite、Playwright、Vitest、Biome 等工具\n\n5. **Rust 开发** (`setup_rust.sh`)\n   - Rust 工具链、cargo 工具、Web 和系统编程相关工具\n\n6. **Java 企业级开发** (`setup_java_enterprise.sh`)\n   - Java 21 LTS、SDKMAN、Gradle 8.11+、Maven 3.9+、JBang\n\n7. **Bash\u002FZsh 脚本编写** (`setup_bash_zsh.sh`)\n   - Shell 开发工具及最佳实践\n\n8. **云原生 DevOps** (`setup_cloud_native_devops.sh`)\n   - Docker、Kubernetes、Terraform、各类云工具\n\n9. **GenAI\u002FLLM 运维** (`setup_genai_llm_ops.sh`)\n   - 机器学习\u002F人工智能开发工具与框架\n\n10. **数据工程** (`setup_data_engineering.sh`)\n    - 数据处理与分析相关工具\n\n11. **无服务器边缘计算** (`setup_serverless_edge.sh`)\n    - 无服务器与边缘计算相关工具\n\n12. **Terraform Azure** (`setup_terraform_azure.sh`)\n    - Terraform、Azure CLI、基础设施相关工具\n\n13. **Angular** (`setup_angular.sh`)\n    - Node.js、Angular CLI、TypeScript、测试工具\n\n14. **Flutter** (`setup_flutter.sh`)\n    - Flutter SDK、Dart、Android Studio、开发工具\n\n15. **React Native** (`setup_react_native.sh`)\n    - React Native CLI、移动开发相关工具\n\n此外还提供以下设置脚本：\n- **PHP\u002FLaravel** (`setup_php_laravel.sh`)\n- **C++ 系统开发** (`setup_cpp_systems.sh`)\n- **Solana\u002FAnchor** (`setup_solana_anchor.sh`)\n- **Ansible** (`setup_ansible.sh`)\n- **LLM 开发测试** (`setup_llm_dev_testing.sh`)\n- **LLM 评估与可观ility** (`setup_llm_eval_observability.sh`)\n- **Kubernetes AI 推理** (`setup_kubernetes_ai_inference.sh`)\n\n### 设置功能\n\n- 🎨 **交互式且安全**：彩色提示信息，安装前始终询问确认\n- 🔍 **智能检测**：检查现有安装情况以避免冲突\n- 🛡️ **非破坏性**：未经许可不会覆盖现有配置\n- 🪟 **兼容多种 Shell**：支持 bash 和 zsh\n- 📊 **进度跟踪**：显示已安装和待安装的内容\n\n## 📖 架构说明\n\n### 双脚本系统\n\n该项目由两个独立但协同工作的脚本组成：\n\n#### 1. **Python 脚本** (`claude_code_agent_farm.py`) - 大脑 🧠\n\n这是主要的协调器，负责执行所有核心任务：\n\n- 创建并管理带有多个窗格的 tmux 会话\n- 通过运行配置的命令生成问题文件\n- 在每个 tmux 窗格中启动 Claude Code 代理\n- 监控代理的健康状况（上下文使用、工作状态、错误）\n- 自动重启完成任务或遇到问题的代理\n- 在 tmux 控制窗口中运行监控仪表板\n- 支持通过 Ctrl+C 优雅关闭\n- 管理设置的备份与恢复，防止损坏\n- 实现文件锁机制以确保并发访问安全\n- 将监控状态写入 JSON 文件以便外部监控\n\n**您只需运行此脚本，它就会持续运行**（除非使用 `--no-monitor` 模式）。监控仪表板显示在 tmux 会话的控制窗口中，而不是启动终端中。\n\n#### 2. **Shell 脚本** (`view_agents.sh`) - 窗口 🪟\n\n这是一个可选的便捷工具，用于查看 tmux 会话：\n\n- **不与 Python 脚本交互**\n- **在单独的终端中运行**以查看代理活动\n- **提供不同的查看模式**（网格、聚焦、分屏）\n- **仅是 tmux 命令的封装**，方便使用\n- **自动建议调整字体大小**以适应大量代理\n\n可以这样理解：\n- **Python 脚本** = 您的汽车引擎（负责所有工作）\n- **Shell 脚本** = 您的仪表盘摄像头（让您看到正在发生的事情）\n\n### 隐藏命令\n\n#### 仅监控模式\n有一个隐藏命令可用于仅运行监控界面：\n\n```bash\nclaude-code-agent-farm monitor-only --path \u002Fproject --session claude_agents\n```\n\n该命令读取监控状态文件并显示仪表板，而无需启动代理。\n\n### 为什么采用双脚本设计？\n\n1. **职责分离**：核心逻辑（Python）与查看工具（Shell）\n2. **灵活性**：您可以仅监控代理，而不使用查看脚本\n3. **独立性**：任一脚本均可独立使用，无需另一脚本配合\n\n## 🎮 支持的工作流\n\n### 1. Bug 修复工作流\n\n代理并行处理类型检查和 linter 问题：\n- 运行您配置的类型检查和 linter 命令\n- 生成合并的问题文件\n- 代理随机选择部分问题进行修复\n- 标记已完成的问题以避免重复\n- 专注于修复现有问题\n- 使用实例特定的种子以提高随机化效果\n\n### 2. 最佳实践实施工作流\n\n代理系统地实施现代最佳实践：\n- 阅读全面的最佳实践指南\n- 创建进度跟踪文档（`@\u003CSTACK>_BEST_PRACTICES_IMPLEMENTATION_PROGRESS.md`）\n- 分阶段实施改进措施\n- 跟踪每条准则的完成百分比\n- 保持会话之间的连续性\n- 支持通过特殊提示继续之前的工作\n\n### 3. 协作智能体工作流（高级）\n\n最复杂的 workflow 选项可以将智能体集群转变为一支协调一致的开发团队，从而实现复杂且具有战略意义的改进。令人惊讶的是，这一强大功能完全通过提示文件来实现！无需编写任何实际代码即可运行该系统；相反，大语言模型（尤其是 Opus 4）已经足够智能，能够理解并可靠地自主执行整个系统：\n\n#### 多智能体协调系统\n\n此工作流实现了一种分布式协调协议，允许多个智能体同时在同一个代码库上协作而不会产生冲突。系统会在您的项目中创建一个 `\u002Fcoordination\u002F` 目录结构：\n\n```\n\u002Fcoordination\u002F\n├── active_work_registry.json     # 所有正在进行工作的中央注册表\n├── completed_work_log.json       # 已完成任务的日志  \n├── agent_locks\u002F                  # 智能体锁文件目录\n│   └── {agent_id}_{timestamp}.lock\n└── planned_work_queue.json       # 计划但尚未开始的工作队列\n```\n\n#### 工作原理\n\n1. **唯一智能体身份**：每个智能体生成一个唯一的 ID（`agent_{timestamp}_{random_4_chars}`）\n\n2. **工作申领流程**：在开始任何工作之前，智能体必须：\n   - 检查活跃工作注册表以避免冲突\n   - 创建锁文件以申领特定的文件和功能\n   - 将其工作计划连同详细范围信息一起注册\n   - 在整个工作周期中持续更新其状态\n\n3. **防止冲突**：锁文件系统可防止多个智能体：\n   - 同时修改同一文件\n   - 实现重叠的功能\n   - 产生合并冲突或破坏性变更\n   - 重复已完成的工作\n\n4. **智能工作分配**：智能体自动：\n   - 从可用任务中选择不冲突的工作\n   - 如果首选文件已被锁定，则将工作加入队列\n   - 智能处理过期锁文件（超过 2 小时）\n   - 通过描述性的 Git 提交进行协调\n\n#### 为何效果良好\n\n该协调系统解决了几个关键问题：\n\n- **消除合并冲突**：基于锁的文件申领机制确保了干净的并行开发\n- **防止重复劳动**：智能体在开始工作前会检查已完成工作日志\n- **支持复杂任务**：与简单的 Bug 修复不同，智能体可以处理战略性改进\n- **保持代码稳定性**：功能测试要求可防止破坏性变更\n- **高效扩展**：20 多个智能体可以在互不干扰的情况下高效工作\n- **聚焦业务价值**：所有改进都需要经过论证和规划才能实施\n\n#### 高级特性\n\n- **过期锁检测**：自动处理超过 2 小时未使用的锁文件\n- **紧急协调**：针对严重冲突的告警系统\n- **进度透明化**：所有智能体都可以查看其他人在做什么\n- **原子工作单元**：每个智能体在释放锁之前都会完成完整的功能\n- **详细规划**：智能体必须在申领工作前制定全面的计划\n\n#### 最佳使用场景\n\n此工作流特别适用于以下情况：\n- 大规模重构项目\n- 实施复杂的架构变更\n- 在整个代码库中添加全面的类型注解\n- 系统性的性能优化\n- 多方面的安全改进\n- 需要协调的特性开发\n\n要使用此工作流，请指定协作智能体提示文件：\n```bash\nclaude-code-agent-farm \\\n  --path \u002Fproject \\\n  --prompt-file prompts\u002Fcooperating_agents_improvement_prompt_for_python_fastapi_postgres.txt \\\n  --agents 5\n```\n\n## 🌐 技术栈支持\n\n### 34 种支持的技术栈完整列表\n\n该项目包含预配置的支持，涵盖以下领域：\n\n#### Web 开发\n1. **Next.js** - TypeScript、React 和现代 Web 开发\n2. **Angular** - 企业级 Angular 应用程序\n3. **SvelteKit** - 现代 Web 框架\n4. **Remix\u002FAstro** - 全栈 Web 框架\n5. **Flutter** - 跨平台移动开发\n6. **Laravel** - PHP Web 框架\n7. **PHP** - 通用 PHP 开发\n\n#### 系统与编程语言\n8. **Python** - FastAPI、Django 和数据科学工作流\n9. **Rust** - 系统编程和 Web 应用程序\n10. **Rust CLI** - 命令行工具开发\n11. **Go** - Web 服务和云原生应用\n12. **Java** - 使用 Spring Boot 的企业级应用\n13. **C++** - 系统编程和对性能要求极高的应用\n\n#### DevOps 与基础设施\n14. **Bash\u002FZsh** - Shell 脚本和自动化\n15. **Terraform\u002FAzure** - 基础设施即代码\n16. **云原生 DevOps** - Kubernetes、Docker 和 CI\u002FCD\n17. **Ansible** - 基础设施自动化和配置管理\n18. **HashiCorp Vault** - 密钥管理和策略即代码\n\n#### 数据与 AI\n19. **GenAI\u002FLLM Ops** - AI\u002FML 运营和工具链\n20. **LLM 开发测试** - LLM 开发和测试工作流\n21. **LLM 评估与可观性** - LLM 评估和监控\n22. **数据工程** - ETL、分析和大数据\n23. **数据湖** - Kafka、Snowflake 和 Spark 集成\n24. **Polars\u002FDuckDB** - 高性能数据处理\n25. **Excel 自动化** - 基于 Python 的 Excel 自动化，并结合 Azure 使用\n26. **PostgreSQL 17 与 Python** - 现代 PostgreSQL 17 结合 FastAPI\u002FSQLModel\n\n#### 特殊领域\n27. **无服务器边缘计算** - 边缘计算和无服务器架构\n28. **Kubernetes 上的 AI 推理** - 在 Kubernetes 上进行 AI 推理\n29. **安全工程** - 安全最佳实践和工具\n30. **硬件开发** - 嵌入式系统和硬件设计\n31. **Unreal Engine** - 使用 Unreal Engine 5 进行游戏开发\n32. **Solana\u002FAnchor** - 在 Solana 上进行区块链开发\n33. **Cosmos** - Cosmos 区块链生态系统\n34. **React Native** - 跨平台移动开发\n\n每个技术栈都包含：\n- 优化后的配置文件\n- 针对特定技术的提示\n- 全面的最佳实践指南（共 31 份）\n- 适当的分块大小和时间安排\n\n### 自定义技术栈\n\n您可以创建自己的配置：\n\n```json\n{\n  \"comment\": \"自定义 Rust 配置\",\n  \"tech_stack\": \"rust\",\n  \"problem_commands\": {\n    \"type_check\": [\"cargo\", \"check\"],\n    \"lint\": [\"cargo\", \"clippy\", \"--\", \"-D\", \"warnings\"]\n  },\n  \"best_practices_files\": [\".\u002Fguides\u002FRUST_BEST_PRACTICES.md\"],\n  \"chunk_size\": 30,\n  \"prompt_file\": \"prompts\u002Frust_prompt.txt\",\n  \"agents\": 15,\n  \"max_agents\": 50,\n  \"auto_restart\": true,\n  \"git_branch\": \"feature\u002Frust-improvements\",\n  \"git_remote\": \"origin\"\n}\n```\n\n## ⚙️ 配置系统\n\n### 核心配置选项\n\n```json\n{\n  \"comment\": \"人类可读的描述\",\n  \"tech_stack\": \"nextjs\",\n  \"problem_commands\": {\n    \"type_check\": [\"bun\", \"run\", \"type-check\"],\n    \"lint\": [\"bun\", \"run\", \"lint\"],\n    \"test\": [\"bun\", \"run\", \"test\"]\n  },\n  \"best_practices_files\": [\".\u002Fbest_practices_guides\u002FNEXTJS15_BEST_PRACTICES.md\"],\n  \"chunk_size\": 50,\n  \"agents\": 20,\n  \"max_agents\": 50,\n  \"session\": \"claude_agents\",\n  \"prompt_file\": \"prompts\u002Fdefault_prompt_nextjs.txt\",\n  \"auto_restart\": true,\n  \"context_threshold\": 20,\n  \"idle_timeout\": 60,\n  \"max_errors\": 3,\n  \"git_branch\": null,\n  \"git_remote\": \"origin\",\n  \"tmux_kill_on_exit\": true,\n  \"tmux_mouse\": true,\n  \"stagger\": 10.0,\n  \"wait_after_cc\": 15.0,\n  \"check_interval\": 10,\n  \"skip_regenerate\": false,\n  \"skip_commit\": false,\n  \"no_monitor\": false,\n  \"attach\": false,\n  \"fast_start\": false,\n  \"full_backup\": false\n}\n```\n\n### 关键参数\n\n- **tech_stack**: 技术栈标识（支持34种技术栈之一）\n- **problem_commands**: 用于类型检查、代码格式检查和测试的命令\n- **best_practices_files**: 需要复制到项目中的最佳实践指南\n- **chunk_size**: 每次代理迭代处理的基础行数或变更量（根据剩余工作动态调整）\n- **prompt_file**: 使用哪个提示模板（共有36个可用模板）\n- **agents**: 运行的代理数量（默认：20）\n- **max_agents**: 允许的最大代理数量（默认：50）\n- **auto_restart**: 启用自动重启代理\n- **context_threshold**: 当上下文百分比低于此阈值时，自动清除上下文\n- **git_branch**: 可选的特定分支，用于提交更改\n- **git_remote**: 推送代码的远程仓库名称（默认：origin）\n\n### 命令行选项\n\n所有配置选项都可以通过命令行覆盖：\n\n```bash\nclaude-code-agent-farm \\\n  --path \u002Fproject \\\n  --config configs\u002Fbase.json \\\n  --agents 10 \\\n  --chunk-size 30 \\\n  --auto-restart\n```\n\n#### 完整选项参考\n\n```\n命令:\n  doctor                   运行预启动验证检查\n  monitor-only             显示监控仪表板（内部使用）\n\n必填项:\n  --path PATH               项目根目录\n\n代理配置:\n  --agents N, -n N         代理数量（默认：20）\n  --session NAME, -s NAME  tmux会话名称（默认：claude_agents）\n  --chunk-size N           覆盖配置中的chunk size\n\n时间设置:\n  --stagger SECONDS        代理启动之间的延迟（默认：10.0秒）\n  --wait-after-cc SECONDS  启动代码检查工具后等待的时间（默认：15.0秒）\n  --check-interval SECONDS 健康检查间隔时间（默认：10秒）\n\n功能选项:\n  --skip-regenerate        跳过重新生成问题文件\n  --skip-commit           跳过git提交\u002F推送\n  --auto-restart          启用自动重启代理\n  --no-monitor            仅启动代理并退出\n  --attach                设置完成后附加到tmux会话\n\n高级选项:\n  --prompt-file PATH      自定义提示文件\n  --config PATH           JSON配置文件\n  --context-threshold N    当上下文百分比小于等于N%时，自动清除上下文（默认：20）\n  --idle-timeout SECONDS   代理空闲N秒后标记为空闲状态（默认：60秒）\n  --max-errors N           代理出现N次错误后禁用（默认：3次）\n  --commit-every N         每隔N次重新生成周期后提交一次\n  --tmux-kill-on-exit      退出时杀死tmux会话（默认：true）\n  --no-tmux-kill-on-exit   退出后保持tmux会话运行\n  --tmux-mouse             启用tmux鼠标支持（默认：true）\n  --no-tmux-mouse          禁用tmux鼠标支持\n  --fast-start             跳过shell提示符检测\n  --full-backup            启动前对Claude设置进行完整备份\n```\n\n## 📝 提示系统\n\n### 完整提示库（37个提示）\n\n系统包含适用于所有工作流和技术栈的专用提示：\n\n#### Bug修复提示（4个）\n- `default_prompt.txt` - 通用Bug修复\n- `default_prompt_nextjs.txt` - Next.js专用\n- `default_prompt_python.txt` - Python专用\n- `bug_fixing_prompt_for_nextjs.txt` - 高级Next.js修复\n\n#### 协作代理提示（1个）\n- `cooperating_agents_improvement_prompt_for_python_fastapi_postgres.txt` - 多代理协作系统\n\n#### 最佳实践实施提示（31个）\n- `default_best_practices_prompt.txt` - 通用实施\n- `continue_best_practices_prompt.txt` - 继续现有工作\n\n##### Web开发（7个）\n- `default_best_practices_prompt_nextjs.txt` - Next.js 15\n- `default_best_practices_prompt_angular.txt` - Angular\n- `default_best_practices_prompt_sveltekit.txt` - SvelteKit\n- `default_best_practices_prompt_remix_astro.txt` - Remix\u002FAstro\n- `default_best_practices_prompt_flutter.txt` - Flutter\n- `default_best_practices_prompt_laravel.txt` - Laravel\n- `default_best_practices_prompt_php.txt` - PHP\n\n##### 系统与语言（7个）\n- `default_best_practices_prompt_python.txt` - Python\u002FFastAPI\n- `default_best_practices_prompt_rust_web.txt` - Rust Web应用\n- `default_best_practices_prompt_rust_system.txt` - Rust系统\n- `default_best_practices_prompt_rust_cli.txt` - Rust CLI工具\n- `default_best_practices_prompt_go.txt` - Go应用\n- `default_best_practices_prompt_java.txt` - Java企业应用\n- `default_best_practices_prompt_cpp.txt` - C++系统\n\n##### DevOps与基础设施（5个）\n- `default_best_practices_prompt_bash_zsh.txt` - Shell脚本编写\n- `default_best_practices_prompt_terraform_azure.txt` - IaC\n- `default_best_practices_prompt_cloud_native_devops.txt` - DevOps\n- `default_best_practices_prompt_ansible.txt` - Ansible自动化\n- `default_best_practices_prompt_vault.txt` - HashiCorp Vault\n\n##### 数据与AI（7个）\n- `default_best_practices_prompt_genai_llm_ops.txt` - AI\u002FML运维\n- `default_best_practices_prompt_llm_dev_testing.txt` - LLM开发\n- `default_best_practices_prompt_llm_eval_observability.txt` - LLM评估与可观ility\n- `default_best_practices_prompt_data_engineering.txt` - 数据管道\n- `default_best_practices_prompt_data_lakes.txt` - 数据湖\n- `default_best_practices_prompt_polars.txt` - Polars\u002FDuckDB\n- `default_best_practices_prompt_excel.txt` - Excel自动化\n\n##### 专用领域（7个）\n- `default_best_practices_prompt_serverless_edge.txt` - 边缘计算\n- `default_best_practices_prompt_kubernetes_ai.txt` - Kubernetes AI\n- `default_best_practices_prompt_security.txt` - 安全工程\n- `default_best_practices_prompt_hardware.txt` - 硬件开发\n- `default_best_practices_prompt_unreal.txt` - Unreal Engine\n- `default_best_practices_prompt_solana.txt` - Solana区块链\n- `default_best_practices_prompt_cosmos.txt` - Cosmos区块链\n- `default_best_practices_prompt_react_native.txt` - React Native\n\n### 变量替换\n\n提示支持动态变量：\n- `{chunk_size}` - 替换为配置的chunk size\n\n提示示例：\n```\n每次处理大约{chunk_size}处改进...\n```\n\n## 🔄 工作原理\n\n### 错误修复工作流\n\n1. **问题生成**：运行类型检查、代码 lint 和测试命令\n2. **代理启动**：在 tmux 窗格中启动 N 个代理\n3. **任务分配**：每个代理随机选择问题片段\n4. **冲突预防**：将已完成的问题标记为 [COMPLETED]\n5. **进度跟踪**：提交更改，并附带丰富的差异摘要，显示文件数量和变更统计信息\n\n### 最佳实践工作流\n\n1. **指南分发**：将最佳实践指南复制到项目中\n2. **进度文档**：代理创建或更新跟踪文档\n3. **系统化实施**：逐步执行指南中的各项建议\n4. **准确跟踪**：保持诚实的完成百分比\n5. **会话连续性**：进度在多次运行之间持续保留\n\n### 安全特性\n\n1. **设置备份**：在启动前自动备份 Claude 设置\n   - 在项目目录下的 `.claude_agent_farm_backups\u002F` 中创建带时间戳的备份\n   - 自动轮换保存最近 10 个备份\n   - 强制限制总大小不超过 200MB，防止磁盘空间膨胀\n   - 提供 `--full-backup` 标志以进行完整备份\n   - 清理后报告备份存储状态\n2. **设置恢复**：检测到损坏时从备份恢复\n   - 自动检测设置错误\n   - 在代理启动时无缝恢复\n3. **文件锁定**：使用文件锁防止并发访问问题\n   - 锁文件位于 `~\u002F.claude\u002F.agent_farm_launch.lock`\n   - 检测并清理 30 秒以上的过期锁\n   - 防止同时启动多个 Claude 实例导致设置损坏\n4. **权限管理**：自动修复文件权限\n   - 将 `settings.json` 的权限设置为 600\n   - 将 `.claude` 目录的权限设置为 700\n   - 确保正确的文件所有权\n5. **原子操作**：使用原子文件操作以确保安全\n6. **紧急清理**：优雅地处理意外退出\n   - 清理 tmux 会话\n   - 删除锁文件\n   - 删除状态文件\n7. **启动锁定**：通过锁文件防止同时启动多个 Claude 实例\n8. **自适应延迟**：根据成功或失败智能调整启动延迟\n   - 前一次启动成功时，延迟时间减半（健康状态下更快启动）\n   - 前一次启动失败时，延迟时间加倍（保持安全性）\n   - 最大延迟设为 60 秒，以防过度延迟\n9. **代理数量限制**：强制执行 `max_agents` 限制（默认：50）\n10. **实例随机化**：为每个代理添加唯一种子，以更好地分配工作\n\n## 📊 监控仪表板\n\n该 Python 脚本包含一个实时监控仪表板，显示：\n\n- **代理状态**：工作中、空闲、上下文不足、错误、已禁用\n- **上下文使用情况**：代理上下文窗口的使用百分比，并配有视觉警告\n- **心跳间隔**：自上次代理活动脉冲以来的时间（按颜色编码）\n- **上次活动**：代理上次执行操作的时间\n- **上次错误**：最近的错误消息（如果有）\n- **会话统计**：总重启次数、运行时间、活跃代理数\n- **周期计数**：已完成的工作周期数\n\n### 上下文警告\n\n每个 tmux 窗格的标题栏都会显示上下文警告：\n- ⚠️ **严重**（≤20%）：代理即将清除上下文\n- ⚡ **低**（≤30%）：上下文即将耗尽\n- 健康水平则显示正常百分比\n\n### 内置仪表板\n\n监控仪表板运行在 tmux 控制器窗口中：\n\n```\nClaude 代理农场 - 14:32:15\n┏━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┓\n┃ 代理    ┃ 状态     ┃ 周期 ┃ 上下文  ┃ 运行时间      ┃ 心跳┃ 错误 ┃\n┡━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━┩\n│ 窗格 00  │ 工作中    │ 2      │ 75%      │ 0:05:23      │ 12s      │ 0      │\n│ 窗格 01  │ 工作中    │ 2      │ 82%      │ 0:05:19      │ 8s       │ 0      │\n│ 窗格 02  │ 空闲       │ 3      │ 45%      │ 0:05:15      │ 45s      │ 0      │\n└──────────┴────────────┴────────┴──────────┴──────────────┴──────────┴────────┘\n```\n\n### 查看选项\n\n```bash\n# 使用查看脚本\n.\u002Fview_agents.sh\n\n# 直接使用 tmux 命令\ntmux attach -t claude_agents\ntmux attach -t claude_agents:controller  # 仅仪表板\n```\n\n### 上下文重置宏\n\n在任何 tmux 窗口中按下 `Ctrl+R`，即可向所有代理同时广播 `\u002Fclear` 命令。只需一次按键，即可释放所有代理的上下文，特别适用于多个代理上下文不足的情况。\n\n### 代理状态\n\n- 🟡 **starting** - 代理正在初始化\n- 🟢 **working** - 正在积极处理任务\n- 🔵 **ready** - 等待输入\n- 🟡 **idle** - 已完成工作\n- 🔴 **error** - 检测到问题\n- ⚫ **unknown** - 状态不明\n\n### 自动重启功能\n\n当启用 `--auto-restart` 时：\n- 通过心跳文件持续监控代理健康状况\n- 对出现错误、进入空闲状态或心跳过期（超过 2 分钟）的代理进行重启\n- 监控上下文使用百分比，并在低于阈值时清除上下文\n- 自适应空闲超时会根据代理的工作模式调整\n  - 跟踪所有代理的周期完成时间\n  - 将超时设置为周期时间中位数的 3 倍（范围 30 秒至 600 秒）\n  - 防止复杂任务中的误判\n  - 加快简单任务的检测速度\n- 实施指数退避策略以防止重启循环\n  - 初始等待时间为 10 秒\n  - 每次重启等待时间翻倍（最长 5 分钟）\n- 记录每个代理的重启次数\n- 达到最大错误次数后禁用代理\n\n### 监控状态文件\n\n系统会将监控状态写入项目目录下的 `.claude_agent_farm_state.json` 文件。该文件包含：\n- 代理状态和健康指标\n- 会话信息\n- 运行统计信息\n\n结构如下：\n```json\n{\n  \"session\": \"claude_agents\",\n  \"num_agents\": 20,\n  \"agents\": {\n    \"0\": {\n      \"status\": \"working\",\n      \"start_time\": \"2024-01-15T10:30:00\",\n      \"last_activity\": \"2024-01-15T10:35:00\",\n      \"last_restart\": null,\n      \"cycles\": 2,\n      \"last_context\": 75,\n      \"errors\": 0,\n      \"restart_count\": 0\n    }\n  },\n  \"start_time\": \"2024-01-15T10:30:00\",\n  \"timestamp\": \"2024-01-15T10:35:00\"\n}\n```\n\n外部工具可以读取此文件来监控农场的进展。\n\n### HTML 运行报告\n\n每次运行结束时，系统会生成一份全面的 HTML 报告，内容包括：\n\n- **运行摘要**：持续时间、使用的代理数量、修复的问题数、提交的次数\n- **代理性能**：单个代理的统计信息，包括周期数、上下文使用情况、错误和重启次数\n- **配置详情**：本次运行使用的所有设置\n- **可视化格式**：丰富的 HTML 输出，带有语法高亮和深色主题\n\n报告以 `agent_farm_report_YYYYMMDD_HHMMSS.html` 的形式保存在项目目录中。\n\n特点：\n- 单文件 HTML，内联样式（无外部依赖）\n- 专业级深色主题，专为代码审查优化\n- 可排序表格，带有颜色编码的状态指示器\n- 完整的运行统计信息，可用于文档或拉取请求\n- 在正常关闭时自动生成\n\n## 💡 使用示例\n\n### 快速测试运行\n```bash\n# 5 个代理，跳过 Git 操作\nclaude-code-agent-farm --path \u002Fproject -n 5 --skip-regenerate --skip-commit\n```\n\n### 生产环境 Bug 修复\n```bash\n# 使用 Python 项目进行完整运行\nclaude-code-agent-farm \\\n  --path \u002Fpython\u002Fproject \\\n  --config configs\u002Fpython_uv_config.json \\\n  --agents 15 \\\n  --auto-restart\n```\n\n### 最佳实践实施\n```bash\n# 系统性改进\nclaude-code-agent-farm \\\n  --path \u002Fnextjs\u002Fproject \\\n  --config configs\u002Fnextjs_best_practices_config.json \\\n  --agents 10\n```\n\n### 增量提交\n```bash\n# 每 5 轮提交一次进度\nclaude-code-agent-farm \\\n  --path \u002Fproject \\\n  --config configs\u002Fpython_config.json \\\n  --agents 20 \\\n  --commit-every 5 \\\n  --auto-restart\n```\n\n### 自定义配置\n```bash\n# 覆盖配置设置\nclaude-code-agent-farm \\\n  --path \u002Fproject \\\n  --config configs\u002Fbase.json \\\n  --chunk-size 25 \\\n  --context-threshold 15 \\\n  --idle-timeout 120\n```\n\n### 无头运行\n```bash\n# 在 CI\u002FCD 中无需监控的运行\nclaude-code-agent-farm \\\n  --path \u002Fproject \\\n  --config configs\u002Fci-config.json \\\n  --no-monitor \\\n  --auto-restart\n```\n\n### 专用技术栈\n```bash\n# Angular 开发\nclaude-code-agent-farm \\\n  --path \u002Fangular\u002Fproject \\\n  --config configs\u002Fangular_config.json\n\n# 区块链开发\nclaude-code-agent-farm \\\n  --path \u002Fsolana\u002Fproject \\\n  --config configs\u002Fsolana_anchor_config.json\n\n# 数据工程\nclaude-code-agent-farm \\\n  --path \u002Fdata\u002Fproject \\\n  --config configs\u002Fpolars_duckdb_config.json\n```\n\n### 协作智能体模式\n```bash\n# 针对复杂改进的高级多智能体协作\nclaude-code-agent-farm \\\n  --path \u002Fproject \\\n  --prompt-file prompts\u002Fcooperating_agents_improvement_prompt_for_python_fastapi_postgres.txt \\\n  --agents 20 \\\n  --auto-restart\n```\n\n## 🚨 故障排除\n\n### 常见问题\n\n#### 智能体未启动\n- 验证 `cc` 别名：`alias | grep cc`\n- 手动测试 Claude Code：`cc`\n- 检查 API 密钥配置\n- 增加 `--wait-after-cc` 的等待时间\n- 如果怀疑配置损坏，使用 `--full-backup` 标志\n\n#### 配置错误\n- 验证 JSON 语法\n- 确保所有路径正确\n- 检查命令是否可用（mypy、ruff 等）\n- 确认最佳实践指南存在\n\n#### 资源问题\n- 每个智能体占用约 500MB 内存\n- 如有必要，减少智能体数量\n- 使用 `htop` 监控资源使用情况\n- 检查日志存储的磁盘空间\n- 遵守最大智能体数量限制（默认 50）\n\n#### 设置损坏\n- 系统会自动备份设置\n- 检测到错误时会从备份恢复\n- 手动恢复：检查 `~\u002F.claude\u002Fbackups\u002F`\n- 使用 `--full-backup` 进行全面备份\n\n### 调试功能\n\n- **状态文件**：查看 `.claude_agent_farm_state.json` 以了解智能体状态\n- **心跳文件**：监控 `.heartbeats\u002Fagent*.heartbeat` 以跟踪活动\n- **锁文件**：在 `~\u002F.claude\u002F` 中查找 `.agent_farm_launch.lock`\n- **备份目录**：项目中的 `.claude_agent_farm_backups\u002F` 存放设置备份\n- **预检**：运行 `claude-code-agent-farm doctor` 诊断问题\n- **紧急清理**：Ctrl+C 触发优雅关闭\n  - 第一次 Ctrl+C：优雅关闭并清理智能体\n  - 第二次 Ctrl+C 在 3 秒内：强制终止 tmux 会话\n  - 自动清理状态文件和锁文件\n- **手动 tmux**：`tmux kill-session -t claude_agents` 可强制清理\n\n## 📁 项目结构\n\n```\nclaude_code_agent_farm\u002F\n├── claude_code_agent_farm.py    # 主调度器\n├── view_agents.sh               # tmux 查看工具\n├── setup.sh                     # 自动化设置\n├── pyproject.toml              # Python 项目配置\n├── uv.lock                     # 锁定的依赖项\n├── .envrc                      # direnv 配置\n├── .gitignore                  # Git 忽略模式\n├── configs\u002F                     # 33 个配置文件\n│   ├── nextjs_config.json      # Next.js Bug 修复\n│   ├── python_config.json      # Python Bug 修复\n│   ├── python_uv_config.json   # Python 使用 uv\n│   ├── nextjs_best_practices_config.json\n│   ├── angular_config.json     # Angular 开发\n│   ├── flutter_config.json     # Flutter 移动应用\n│   ├── rust_system_config.json # Rust 系统编程\n│   ├── rust_webapps_config.json # Rust Web 应用\n│   ├── rust_cli_config.json    # Rust CLI 工具\n│   ├── go_webapps_config.json  # Go Web 开发\n│   ├── java_enterprise_config.json # Java 企业级应用\n│   ├── cpp_systems_config.json # C++ 系统\n│   ├── php_config.json         # PHP 开发\n│   ├── laravel_config.json     # Laravel 框架\n│   ├── sveltekit2_config.json  # SvelteKit 框架\n│   ├── remix_astro_config.json # Remix\u002FAstro 框架\n│   ├── bash_zsh_config.json    # Shell 脚本\n│   ├── terraform_azure_config.json # Infrastructure as Code\n│   ├── cloud_native_devops_config.json # DevOps 工具\n│   ├── ansible_config.json     # Ansible 自动化\n│   ├── vault_config.json       # HashiCorp Vault\n│   ├── genai_llm_ops_config.json # AI\u002FML 运营\n│   ├── data_engineering_config.json # 数据管道\n│   ├── data_lakes_config.json  # Kafka\u002FSnowflake\u002FSpark\n│   ├── polars_duckdb_config.json # 数据处理\n│   ├── excel_automation_config.json # Excel 自动化\n│   ├── serverless_edge_config.json # 边缘计算\n│   ├── security_engineering_config.json # 安全\n│   ├── hardware_dev_config.json # 硬件开发\n│   ├── unreal_engine_config.json # 游戏开发\n│   ├── solana_anchor_config.json # Solana 区块链\n│   ├── cosmos_blockchain_config.json # Cosmos 区块链\n│   └── sample.json             # 示例配置\n├── prompts\u002F                     # 37 个提示模板\n│   ├── Bug 修复提示（4 个）\n│   ├── 协作智能体提示（1 个）\n│   ├── 通用最佳实践提示（2 个）\n│   └── 技术栈特定的最佳实践提示（30 个）\n├── best_practices_guides\u002F       # 35 份最佳实践文档\n│   ├── Web 开发（7 份指南）\n│   ├── 系统与语言（7 份指南）\n│   ├── DevOps 与基础设施（5 份指南）\n│   ├── 数据与 AI（6 份指南）\n│   └── 特殊领域（6 份指南）\n├── tool_setup_scripts\u002F          # 24 个开发环境设置脚本\n│   ├── setup.sh                # 交互式菜单\n│   ├── common_utils.sh         # 共享工具\n│   ├── README.md              # 设置脚本说明\n│   ├── Web 开发（4 个脚本）\n│   ├── 系统与语言（3 个脚本）\n│   ├── DevOps 与基础设施（3 个脚本）\n│   └── 数据与 AI（3 个脚本）\n└── __pycache__\u002F                # Python 缓存（已忽略于 git）\n```\n\n## 🔧 高级主题\n\n### 创建自定义工作流\n\n1. **定义你的技术栈配置**（参阅 34 个示例）\n2. **创建合适的提示**（遵循 37 个现有模式）\n3. **添加最佳实践指南**（可选，参阅 35 个示例）\n4. **配置问题检测命令**（类型检查、代码风格检查、测试）\n5. **设置合适的分块大小**（根据复杂度选择 20-75）\n6. **先用少量智能体进行测试**\n\n### 扩展性考量\n\n- 从小规模开始（5–10个代理），逐步扩展\n- 默认最大支持50个代理（可通过`max_agents`配置）\n- 当代理数量较多时，增加启动间隔时间\n- 对于50个以上的代理，建议分批运行\n- 使用`--no-monitor`进行无头模式运行\n- 监控系统资源（内存、CPU）\n- 根据性能调整分块大小\n\n### 与CI\u002FCD集成\n\n```bash\n#!\u002Fbin\u002Fbash\n# 自动化代码改进脚本\nclaude-code-agent-farm \\\n  --path $PROJECT_PATH \\\n  --config configs\u002Fci-config.json \\\n  --no-monitor \\\n  --auto-restart \\\n  --skip-commit \\\n  --agents 10\n```\n\n### 自定义Git工作流\n\n在配置文件中设置自定义的Git分支和远程仓库：\n\n```json\n{\n  \"git_branch\": \"feature\u002Fai-improvements\",\n  \"git_remote\": \"upstream\",\n  \"skip_commit\": false\n}\n```\n\n### 性能调优\n\n- **分块大小**：根据剩余工作量自动调整\n  - 按技术栈设定基础值：Python（50）、Next.js（50）、Rust（30）、Go（40）、Java（35）\n  - 动态公式：`max(10, total_lines \u002F agents \u002F 2)`\n  - 防止代理过早完成任务或处理琐碎工作\n- **启动间隔时间**：基于启动成功率自适应调整\n  - 默认基线为10秒，防止配置损坏\n  - 前一次启动成功时自动减半（最小值为基线）\n  - 前一次启动失败时则加倍（最大60秒）\n  - 系统健康时可实现更快的启动速度\n- **上下文阈值**：降低该值（15–20%）可更早清除上下文\n- **空闲超时**：根据任务复杂度调整\n- **检查间隔**：在响应速度和CPU占用之间取得平衡\n- **心跳监控**：检测卡住的代理（超过2分钟未发送心跳）\n- **最大代理数**：对于高性能系统可调高至50以上\n- **清理后等待时间**：默认15秒，确保Claude完全就绪\n  - 若出现启动失败，可适当延长\n- **增量提交**：使用`--commit-every N`定期提交进度\n  - 避免产生难以审查的大规模差异\n  - 跟踪所有代理的最小循环次数以保证一致性\n\n### 高级功能\n\n#### 可中断操作\n- 所有长时间运行的操作均可通过Ctrl+C中断\n- 优雅关闭会保留未完成的工作\n- 在意外退出时执行紧急清理\n\n#### 智能错误检测\n- 能够检测多种错误情况：\n  - 配置损坏\n  - 认证失败\n  - 欢迎\u002F设置界面\n  - 命令未找到错误\n  - 解析错误（TypeError、SyntaxError、JSONDecodeError）\n  - 登录提示及API密钥问题\n- 自动尝试恢复后再禁用代理\n- 恢复过程中不影响其他正常工作的代理\n\n#### 提示中的变量替换\n- `{chunk_size}`：替换为配置的分块大小\n- 支持正则表达式模式，灵活定制提示模板\n\n#### 会话名称验证\n- 仅允许字母、数字、连字符和下划线\n- 防止因非法字符导致tmux报错\n\n#### Shell提示检测\n- 智能等待Shell提示后再发送命令\n- `--fast-start`标志可跳过提示检测以加快启动\n- 同时支持bash和zsh提示\n- 多层稳健的就绪检查机制：\n  1. 被动启发式方法，识别常见提示符号和当前目录名\n  2. 主动探测回退机制，发送带有唯一标记的`echo`并等待响应——即使在极简或高度自定义的提示下也能生效\n- 无缝兼容bash、zsh、fish及其他POSIX兼容Shell\n- `--fast-start`标志可供高级用户选择完全跳过检测，以实现最快启动\n\n#### 用户确认\n- 可中断的确认提示（Ctrl+C使用默认行为）\n- 所有破坏性操作均采用安全默认值\n- 清晰的用户交互信息提示\n\n## 🤝 贡献说明\n\n欢迎贡献！请按以下步骤操作：\n1. Fork仓库\n2. 创建特性分支\n3. 如适用，添加测试\n4. 更新文档\n5. 提交拉取请求\n\n### 添加新技术栈\n1. 在`configs\u002F`目录下创建配置文件（可参考34个示例）\n2. 在`prompts\u002F`目录下添加提示（提供37个示例）\n3. 在`best_practices_guides\u002F`目录下编写最佳实践指南（提供35个示例）\n4. 在`tool_setup_scripts\u002F`目录下添加设置脚本（提供15个示例）\n5. 使用各类项目类型进行全面测试\n6. 更新本README以记录新增内容\n\n## 👨‍💻 作者\n由Jeffrey Emanuel创作（jeffrey.emanuel@gmail.com）\n\n## 📄 许可证\nMIT许可证（附带OpenAI\u002FAnthropic Rider条款）——详见[LICENSE](LICENSE)文件\n\n## ⚠️ 重要提示\n- 运行前务必**备份代码**\n- 提交前仔细**审查更改**\n- 初始运行时使用少量代理进行测试\n- 首次运行时需**监控行为**以确保正常运作\n- 大量代理运行时应**监控资源使用情况**\n- 确保`cc`别名已正确配置\n- 确保Git已配置正确的凭据\n- 严格遵守代理数量限制（默认最大50个）\n- Claude设置会自动备份和恢复\n- 锁文件可防止并发启动和配置损坏\n- 状态文件支持外部监控工具\n\n## 🔍 其他资源\n\n### 监控工具\n- 可监控状态文件（`.claude_agent_farm_state.json`）以实现外部集成\n- 心跳文件（`.heartbeats\u002Fagent*.heartbeat`）跟踪代理活动\n- tmux窗格标题实时显示上下文警告\n- tmux会话日志可用于调试代理问题\n- Git提交历史可用于追踪改进\n\n### 恢复选项\n- 可从项目中的`.claude_agent_farm_backups\u002F`手动恢复设置\n- 清理锁文件：`rm ~\u002F.claude\u002F.agent_farm_launch.lock`\n- 紧急会话清理：`tmux kill-session -t claude_agents`\n- 查看之前会话的HTML运行报告以进行调试\n\n### 性能优化\n- 使用SSD以提升文件I\u002FO性能\n- 每个代理分配500MB内存\n- 考虑API调用的网络带宽\n- 运行期间使用`htop`监控CPU使用情况\n\n---\n\n*祝您农耕愉快！🚜 愿您的代码整洁，代理高效产出。*\n\n## 📊 快速参考\n\n### 技术栈支持汇总\n\n| 类别 | 数量 | 示例 |\n|----------|-------|----------|\n| Web开发 | 8 | Next.js、Angular、Flutter、Laravel、React Native |\n| 系统与语言 | 7 | Python、Rust、Go、Java、C++ |\n| DevOps与基础设施 | 6 | Terraform、Kubernetes、Ansible |\n| 数据与AI | 8 | GenAI\u002FLLM、数据湖、PostgreSQL 17、Polars |\n| 特色领域 | 5 | 安全、硬件、区块链 |\n| **总计** | **34** | |\n\n### 资源汇总\n\n| 资源 | 数量 |\n|----------|-------|\n| 配置文件 | 37 |\n| 提示模板 | 37 |\n| 最佳实践指南 | 35 |\n| 工具设置脚本 | 24 |","# Claude Code Agent Farm 快速上手指南\n\nClaude Code Agent Farm 是一个强大的编排框架，可并行运行多个 Claude Code (`cc`) 会话，通过自动化修复漏洞或系统性实施最佳实践来改进你的代码库。它支持多种技术栈，允许 AI 代理团队协作处理大规模代码优化任务。\n\n## 🛠️ 环境准备\n\n在开始之前，请确保你的系统满足以下要求：\n\n### 系统要求\n- **操作系统**: Linux 或 macOS (Windows 需使用 WSL2)\n- **Python**: 3.13+ (推荐使用 `uv` 管理)\n- **终端复用器**: `tmux`\n- **版本控制**: `git`\n- **核心工具**: [Claude Code](https:\u002F\u002Fclaude.ai\u002Fcode) (需安装 `claude` 命令并配置 API Key)\n\n### 前置依赖\n根据你的项目类型，可能还需要安装特定工具（如 Next.js 项目需要 `bun`，Python 项目需要 `mypy`\u002F`ruff` 等）。\n\n> **注意**：本项目依赖一个特殊的 `cc` 别名来启动带有必要权限的 Claude Code。 setup 脚本会自动配置此别名：\n> ```bash\n> alias cc=\"ENABLE_BACKGROUND_TASKS=1 claude --dangerously-skip-permissions\"\n> ```\n\n## 📦 安装步骤\n\n### 1. 克隆仓库并运行设置脚本\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fclaude_code_agent_farm.git\ncd claude_code_agent_farm\nchmod +x setup.sh\n.\u002Fsetup.sh\n```\n\n**设置脚本将自动执行以下操作：**\n- 检查并安装缺失的前置依赖\n- 创建 Python 3.13 虚拟环境\n- 安装所有 Python 依赖\n- 自动配置 `cc` 别名（检测并修复常见的引号错误）\n- 设置 `direnv` 以实现环境自动激活\n- 自动适配 bash 和 zsh shell\n\n### 2. 验证安装\n运行预飞行检查器以确保一切配置正确：\n\n```bash\nclaude-code-agent-farm doctor --path \u002Fpath\u002Fto\u002Fyour\u002Fproject\n```\n\n该命令会检查 Python 版本、必需工具（tmux, git, uv）、Claude Code 配置、API Keys 以及项目特定工具的可用性。\n\n### 3. (可选) 启用 Shell 自动补全\n为了更快的命令输入体验：\n\n```bash\n# 自动检测当前 shell 并安装补全\nclaude-code-agent-farm install-completion\n\n# 或指定 shell 类型\nclaude-code-agent-farm install-completion --shell zsh\n```\n\n## 🚀 基本使用\n\n### 场景一：自动化修复 Bug\n让多个 Agent 并行处理类型检查和 Linter 报错。\n\n**Next.js 项目示例：**\n```bash\nclaude-code-agent-farm --path \u002Fpath\u002Fto\u002Fnextjs-project --config configs\u002Fnextjs_config.json\n```\n\n**Python 项目示例：**\n```bash\nclaude-code-agent-farm --path \u002Fpath\u002Fto\u002Fpython-project --config configs\u002Fpython_config.json\n```\n\n### 场景二：系统性实施最佳实践\n首先将最佳实践指南复制到项目中，然后运行专用配置。\n\n```bash\n# 1. 复制最佳实践指南 (以 Next.js 15 为例)\ncp best_practices_guides\u002FNEXTJS15_BEST_PRACTICES.md \u002Fpath\u002Fto\u002Fyour-project\u002Fbest_practices_guides\u002F\n\n# 2. 运行最佳实践工作流\nclaude-code-agent-farm --path \u002Fpath\u002Fto\u002Fyour-project --config configs\u002Fnextjs_best_practices_config.json\n```\n\n### 💡 使用提示\n- **监控面板**：启动后，主监控面板将在 `tmux` 会话的控制器窗口中显示，而非你启动命令的终端。\n- **查看 Agent 状态**：你可以新开一个终端窗口，运行以下命令查看实时网格视图：\n  ```bash\n  .\u002Fview_agents.sh\n  ```\n- **停止运行**：按 `Ctrl+C` 优雅关闭；若在 3 秒内连续按两次 `Ctrl+C` 则强制终止。\n- **清空上下文**：在所有 Agent 中广播 `\u002Fclear` 命令，只需在监控界面按 `Ctrl+R`。","某大型电商平台的后端团队需要在周末紧急对遗留的 Python 和 Go 混合代码库进行大规模安全漏洞修复与规范重构，且必须在下周一上线前完成。\n\n### 没有 claude_code_agent_farm 时\n- **串行处理效率极低**：开发人员只能逐个文件手动调用 AI 修复，面对数千个文件，预计耗时超过 48 小时，无法按时交付。\n- **并发冲突频繁**：若多人同时修改不同文件，极易产生 Git 合并冲突，协调成本高昂且容易出错。\n- **上下文丢失严重**：单个 AI 会话在处理大文件时频繁达到上下文限制，导致修复逻辑中断，需要人工反复重新输入指令。\n- **进度难以监控**：缺乏统一的实时看板，管理者无法直观看到哪些模块正在修复、哪些代理已卡死，只能靠人工轮询确认。\n\n### 使用 claude_code_agent_farm 后\n- **并行加速数十倍**：启动 30+ 个 Claude Code 代理同时工作，利用多技术栈支持同步处理 Python 和 Go 代码，将原本两天的工作量压缩至 3 小时内完成。\n- **自动锁机制防冲突**：内置的基于锁的协调系统自动分配任务文件，确保多个代理不会同时修改同一资源，彻底消除合并冲突。\n- **智能上下文管理**：代理在接近上下文极限时自动清理记忆，并通过一键广播功能同步状态，保证长链路修复任务的连续性。\n- **全景实时监控**：通过 tmux 实时仪表盘清晰展示每个代理的心跳状态和修复进度，异常代理自动重启，管理者一目了然。\n\nclaude_code_agent_farm 将原本需要全员加班数天的“人海战术”重构任务，转变为单人指挥、数十个 AI 代理并行作业的自动化流水线，极大提升了代码治理的时效性与安全性。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FDicklesworthstone_claude_code_agent_farm_426e0a15.png","Dicklesworthstone","Jeff Emanuel","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002FDicklesworthstone_c96b6d22.jpg","Building in NY",null,"doodlestein","https:\u002F\u002Fwww.jeffreyemanuel.com\u002F","https:\u002F\u002Fgithub.com\u002FDicklesworthstone",[81,85],{"name":82,"color":83,"percentage":84},"Shell","#89e051",77,{"name":86,"color":87,"percentage":88},"Python","#3572A5",23,776,83,"2026-04-06T10:44:03","NOASSERTION",4,"Linux, macOS","未说明",{"notes":97,"python":98,"dependencies":99},"该工具是一个编排框架，用于并行运行多个 Claude Code 代理，本身不依赖本地 GPU 进行模型推理（依赖 Anthropic API）。必须安装 tmux 进行终端多路复用。需要配置特殊的 'cc' 别名以启用后台任务和跳过权限确认（ENABLE_BACKGROUND_TASKS=1 claude --dangerously-skip-permissions）。支持通过脚本自动安装 34 种技术栈的开发工具（如 Node.js, Rust, Go 等）。建议使用 uv 管理 Python 环境，并可选安装 direnv 实现环境自动激活。","3.13+",[100,101,102,103,104],"uv","tmux","git","claude-code (cc)","direnv (可选)",[13],[107,108,109,110,101],"ai-agents","automation","developer-tools","python","2026-03-27T02:49:30.150509","2026-04-07T18:40:18.145129",[114,119,123],{"id":115,"question_zh":116,"answer_zh":117,"source_url":118},22737,"这个项目与 Claude Code 官方推出的团队（Team）功能有什么区别？","该项目是对官方功能的补充而非替代。主要区别在于：\n1. **会话模式不同**：Claude Code 的团队功能是在单个会话内路由任务；而本项目运行的是持久化、循环执行的代理（agents）。\n2. **状态管理**：本项目的每个代理启动时设计为无状态，但系统通过外部账本（external ledger）在多次启动间积累记忆。\n3. **适用场景**：团队模式解决单次会话任务，而本项目的“群聊模式”（swarm mode）旨在实现长期（如数月）的自动化运行，即在用户休息时也能持续交付成果。","https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fclaude_code_agent_farm\u002Fissues\u002F2",{"id":120,"question_zh":121,"answer_zh":122,"source_url":118},22738,"在使用多代理设置时，有哪些具体的节省 Token 的策略？","根据生产环境经验，以下策略能显著节省 Token：\n1. **片段纪律（Fragment discipline）**：每个代理启动时都会加载相同的宪法片段（constitutional fragments）。必须严格审计这些片段，如果某个片段不能证明能改变代理行为（非承重部分），应立即删除。避免让 CLAUDE.md 或宪法文件无限增长，这是最大的 Token 泄露源。\n2. **模型选择**：在非关键任务中使用 `--model` 标志指定更便宜的模型。\n3. **任务批处理**：将工作分批处理以减少上下文开销。",{"id":124,"question_zh":125,"answer_zh":126,"source_url":127},22739,"仓库中是否包含 AGENTS.md 文件以指导代理工作流和安全规则？","目前该仓库已弃用（deprecated\u002Fabandoned），维护者明确表示不再计划添加新文件或进行任何更改，因此不会添加 AGENTS.md 文件。","https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fclaude_code_agent_farm\u002Fissues\u002F1",[]]