{"id":29806306,"url":"https://github.com/Dicklesworthstone/claude_code_agent_farm","last_synced_at":"2025-07-28T14:08:05.684Z","repository":{"id":301663073,"uuid":"1009931254","full_name":"Dicklesworthstone/claude_code_agent_farm","owner":"Dicklesworthstone","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-19T21:13:24.000Z","size":981,"stargazers_count":290,"open_issues_count":0,"forks_count":37,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-07-27T03:56:26.939Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Dicklesworthstone.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-28T01:46:46.000Z","updated_at":"2025-07-26T21:19:38.000Z","dependencies_parsed_at":"2025-06-28T04:28:13.203Z","dependency_job_id":"3b1eb712-c643-419f-97f1-e9548e419ecb","html_url":"https://github.com/Dicklesworthstone/claude_code_agent_farm","commit_stats":null,"previous_names":["dicklesworthstone/claude_code_agent_farm"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Dicklesworthstone/claude_code_agent_farm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dicklesworthstone%2Fclaude_code_agent_farm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dicklesworthstone%2Fclaude_code_agent_farm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dicklesworthstone%2Fclaude_code_agent_farm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dicklesworthstone%2Fclaude_code_agent_farm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Dicklesworthstone","download_url":"https://codeload.github.com/Dicklesworthstone/claude_code_agent_farm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dicklesworthstone%2Fclaude_code_agent_farm/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267527835,"owners_count":24102019,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-28T14:05:56.751Z","updated_at":"2025-07-28T14:08:05.670Z","avatar_url":"https://github.com/Dicklesworthstone.png","language":"Shell","funding_links":[],"categories":["HarmonyOS","Frameworks \u0026 Tools","Agents \u0026 Agent Managers","Shell","Multi-Agent Systems","🆕 Latest \u0026 Featured Agent Collections (August 2025)"],"sub_categories":["Windows Manager","Agent Management","Parallel Processing","**Specialized Frameworks \u0026 Tools**"],"readme":"# Claude Code Agent Farm 🤖🚜\n\n\u003e 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://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\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 /clear 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/restore 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`/`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://github.com/Dicklesworthstone/claude_code_agent_farm.git\ncd claude_code_agent_farm\nchmod +x setup.sh\n./setup.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 /path/to/project\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 /path/to/project --config configs/nextjs_config.json\n\n# Python project\nclaude-code-agent-farm --path /path/to/project --config configs/python_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/NEXTJS15_BEST_PRACTICES.md /path/to/project/best_practices_guides/\n\n# Run with best practices config\nclaude-code-agent-farm --path /path/to/project --config configs/nextjs_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./setup.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/Remix/Astro** (`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 \u0026 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/Zsh 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/LLM Ops** (`setup_genai_llm_ops.sh`)\n   - ML/AI 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/Laravel** (`setup_php_laravel.sh`)\n- **C++ Systems** (`setup_cpp_systems.sh`)\n- **Solana/Anchor** (`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 \u0026 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/restore** 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 /project --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\u003e_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 `/coordination/` directory structure in your project:\n\n```\n/coordination/\n├── active_work_registry.json     # Central registry of all active work\n├── completed_work_log.json       # Log of completed tasks  \n├── agent_locks/                  # 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 (\u003e2 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 /project \\\n  --prompt-file prompts/cooperating_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/Astro** - Full-stack web frameworks\n5. **Flutter** - Cross-platform mobile development\n6. **Laravel** - PHP web framework\n7. **PHP** - General PHP development\n\n#### Systems \u0026 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 \u0026 Infrastructure\n14. **Bash/Zsh** - Shell scripting and automation\n15. **Terraform/Azure** - Infrastructure as Code\n16. **Cloud Native DevOps** - Kubernetes, Docker, CI/CD\n17. **Ansible** - Infrastructure automation and configuration management\n18. **HashiCorp Vault** - Secrets management and policy as code\n\n#### Data \u0026 AI\n19. **GenAI/LLM Ops** - AI/ML operations and tooling\n20. **LLM Dev Testing** - LLM development and testing workflows\n21. **LLM Evaluation \u0026 Observability** - LLM evaluation and monitoring\n22. **Data Engineering** - ETL, analytics, big data\n23. **Data Lakes** - Kafka, Snowflake, Spark integration\n24. **Polars/DuckDB** - High-performance data processing\n25. **Excel Automation** - Python-based Excel automation with Azure\n26. **PostgreSQL 17 \u0026 Python** - Modern PostgreSQL 17 with FastAPI/SQLModel\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/Anchor** - 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\": [\"./guides/RUST_BEST_PRACTICES.md\"],\n  \"chunk_size\": 30,\n  \"prompt_file\": \"prompts/rust_prompt.txt\",\n  \"agents\": 15,\n  \"max_agents\": 50,\n  \"auto_restart\": true,\n  \"git_branch\": \"feature/rust-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\": [\"./best_practices_guides/NEXTJS15_BEST_PRACTICES.md\"],\n  \"chunk_size\": 50,\n  \"agents\": 20,\n  \"max_agents\": 50,\n  \"session\": \"claude_agents\",\n  \"prompt_file\": \"prompts/default_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/changes 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 /project \\\n  --config configs/base.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/push\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/Astro\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 \u0026 Languages (7)\n- `default_best_practices_prompt_python.txt` - Python/FastAPI\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 \u0026 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 \u0026 AI (7)\n- `default_best_practices_prompt_genai_llm_ops.txt` - AI/ML 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/DuckDB\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/update 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/` 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 `~/.claude/.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/failure\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./view_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 `/clear` 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 (\u003e2 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 /project -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 /python/project \\\n  --config configs/python_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 /nextjs/project \\\n  --config configs/nextjs_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 /project \\\n  --config configs/python_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 /project \\\n  --config configs/base.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/CD)\nclaude-code-agent-farm \\\n  --path /project \\\n  --config configs/ci-config.json \\\n  --no-monitor \\\n  --auto-restart\n```\n\n### Specialized Stacks\n```bash\n# Angular development\nclaude-code-agent-farm \\\n  --path /angular/project \\\n  --config configs/angular_config.json\n\n# Blockchain development\nclaude-code-agent-farm \\\n  --path /solana/project \\\n  --config configs/solana_anchor_config.json\n\n# Data engineering\nclaude-code-agent-farm \\\n  --path /data/project \\\n  --config configs/polars_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 /project \\\n  --prompt-file prompts/cooperating_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 `~/.claude/backups/`\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/agent*.heartbeat` for activity tracking\n- **Lock Files**: Look for `.agent_farm_launch.lock` in `~/.claude/`\n- **Backup Directory**: `.claude_agent_farm_backups/` 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/\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/                     # 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/Astro 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/ML operations\n│   ├── data_engineering_config.json # Data pipelines\n│   ├── data_lakes_config.json  # Kafka/Snowflake/Spark\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/                     # 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/       # 35 best practices documents\n│   ├── Web Development (7 guides)\n│   ├── Systems \u0026 Languages (7 guides)\n│   ├── DevOps \u0026 Infrastructure (5 guides)\n│   ├── Data \u0026 AI (6 guides)\n│   └── Specialized Domains (6 guides)\n├── tool_setup_scripts/          # 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 \u0026 Languages (3 scripts)\n│   ├── DevOps \u0026 Infrastructure (3 scripts)\n│   └── Data \u0026 AI (3 scripts)\n└── __pycache__/                # 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/CD\n\n```bash\n#!/bin/bash\n# Automated code improvement script\nclaude-code-agent-farm \\\n  --path $PROJECT_PATH \\\n  --config configs/ci-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/ai-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 / agents / 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 (\u003e2 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/setup 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/` (34 examples to follow)\n2. Add prompts in `prompts/` (37 examples available)\n3. Write best practices guide in `best_practices_guides/` (35 examples)\n4. Add setup script in `tool_setup_scripts/` (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 - 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/agent*.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/` in your project\n- Lock file cleanup: `rm ~/.claude/.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/O 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 \u0026 Languages | 7 | Python, Rust, Go, Java, C++ |\n| DevOps \u0026 Infrastructure | 6 | Terraform, Kubernetes, Ansible |\n| Data \u0026 AI | 8 | GenAI/LLM, 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 |","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDicklesworthstone%2Fclaude_code_agent_farm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDicklesworthstone%2Fclaude_code_agent_farm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDicklesworthstone%2Fclaude_code_agent_farm/lists"}