The Problem

Coordinating multiple Claude Code agents on a single codebase is error-prone. Running them in parallel without coordination causes conflicting edits, wasted API calls, and no visibility into what each agent is doing. Manually supervising 20+ terminal sessions is not viable.

What This Does

claude_code_agent_farm orchestrates parallel Claude Code sessions for automated bug fixing and best-practices sweeps. The core logic lives in claude_code_agent_farm.py (2,154 lines), with 34 stack-specific configurations in configs/ (e.g., python_config.json, nextjs_config.json) and matching prompts in prompts/. Shell scripts in tool_setup_scripts/ install per-stack toolchains.

The framework uses lock-based coordination to prevent agents from editing the same files, tracks progress via git commits, and exposes a real-time tmux dashboard. Auto-recovery restarts stalled agents, and context management clears agent memory near token limits.

How It Is Wired

Execution starts at claude_code_agent_farm.py. The entry point reads a JSON config from configs/, spawns N claude processes (default 20, up to 50 via max_agents), and monitors them through tmux panes. The cc alias—ENABLE_BACKGROUND_TASKS=1 claude --dangerously-skip-permissions—is required for agents to run background tasks.

Control flow: config load → agent spawn → lock acquisition → task dispatch → git commit per change → dashboard update → recovery check. The single Python module handles all orchestration, which is why it carries the highest blast radius: any change to agent lifecycle, locking, or reporting touches this one file.

The module graph is flat: 1 internal module, 0 import edges, no cycles. That simplicity is deceptive—the file's 2,154 lines and max nesting depth of 9 make modifications risky. The 31 tool_setup_scripts/*.sh files share 170 repeated 6-line blocks, so fixing a setup bug requires patching each copy.

How To Use It

git clone https://github.com/moses-y/claude_code_agent_farm.git
cd claude_code_agent_farm
chmod +x setup.sh
./setup.sh

The setup script creates a Python 3.13 virtual environment via uv, installs dependencies from pyproject.toml, and configures the cc alias. Verify with:

claude-code-agent-farm doctor --path /path/to/project

Run a sweep by invoking the farm with a config, e.g. configs/python_config.json for a Python best-practices pass. Each config specifies agents, prompts, and target directories.

Real-World Use

A team migrating a Python FastAPI service to newer patterns would run the Python best-practices config. The farm spawns agents per module, each applying rules from prompts/default_best_practices_prompt_python.txt, committing changes with diff summaries. The tmux dashboard shows per-agent status and context usage; view_agents.sh attaches to the monitoring view.

Code Health & Issues

Static analysis found 13 issues (3 high, 10 medium). High severity: duplicated code blocks across 31 setup scripts (170 repeated 6-line blocks), deep nesting in claude_code_agent_farm.py (depth 9) and setup_java_enterprise.sh, and the oversized claude_code_agent_farm.py. Medium: unclosed file handles, broad exception handling, and high branching density in 7 setup scripts.

SDLC gaps: no CI/CD pipeline, no lockfile for pyproject.toml (non-reproducible builds), and no Dependabot/Renovate for dependency updates. Tests exist (4 files) but no automated gate runs them. License is present; no committed secrets found.

The Bottom Line

The orchestration design is sound and the 34-stack coverage is genuinely useful for teams standardizing code quality across heterogeneous repos. The single-file orchestrator and duplicated setup scripts are the main maintenance risks. Teams already using Claude Code and tmux will get value quickly; others should weigh the setup overhead against the coordination benefits.