Claude Code Agent Farm
Orchestrate 20+ parallel Claude Code agents in tmux to systematically fix bugs and implement best practices, with lock-based coordination preventing conflicts.
Least privilege: the default cc alias is `claude --dangerously-skip-permissions`; 20–50 agents run with all permission checks skipped and auto-invoke tools — a destructive default directly contrary to least privilege (scored 0). User confirmation: tool setup scripts claim ask-before-install and double-Ctrl+C force-kill exists, but no per-action confirmation during core runs (1). Data flow: monitoring dashboard, monitor state JSON, and a detailed two-script architecture are documented (2). Sensitive data: only settings. backup/corruption checks are mentioned; no privacy or API-key handling guidance (1). Dependency security: only typer and rich as core deps with version floors; small surface but no lockfile or audit evidence (2). External effects: automatic git commit/push to origin, with toggles like --skip-commit (2). Rollback: settings backup/restore with rotation plus git commit trail (2). Attribution: named author, email, repo links (2).
Self-consistency: README contradictions — prompt inventory says 37 prompts in one place and '36 available' in another; license badge misrepresents the non-standard rider (1). Dependency availability: minimal core deps with floors, but hard reliance on external claude/tmux/uv, mitigated by doctor checks (2). Failure messages: doctor pre-flight, usage-limit detection, and max_errors thresholds are described, though code-level evidence is not in the provided files (2).
Audience/scenarios: 34 stacks, three workflows, 24 setup scripts — exceptionally well scoped (3). Capability boundaries: honestly documents degraded/inert monitoring with non-Claude CLIs (2). Trigger precision: CLI flags map to config keys with stated defaults (2). Environment fit: POSIX Linux, Python 3.13+, tmux explicitly required; macOS/Windows unsupported per classifier (2).
Information architecture: README well sectioned but extremely long and the supplied text is truncated (2). Install notes: setup.sh, doctor, and completion install form a complete path (3). Naming stability: package, command, and session names consistent throughout (2). Examples/FAQ: many config and command examples; no FAQ or troubleshooting section (2). Known limitations: candid caveats for alternate CLIs; other risks (cost, git contention) thinly covered (2). License: LICENSE is modified MIT with an OpenAI/Anthropic restrictive rider, not OSI-compatible; pyproject claims plain MIT and registry metadata is NOASSERTION — three-way inconsistency (1). Versioning: only 1.0.0 and a Beta classifier, no CHANGELOG (1). Maintenance: named author and Issues link, but no governance or response commitments (2).
Output usability: HTML run reports, rich diff summaries, progress documents, and a monitoring dashboard are described (2). Marginal value: one-command orchestration of parallel Claude Code agents with lock coordination and tmux monitoring fills a genuine niche (3). Cost benefit: defaults of 20 agents (up to 50) on token-billed LLM CLIs with almost no cost guidance or budget controls in the README (1).
Claim traceability: most claims point to concrete files/commands (setup.sh, view_agents.sh, configs/*.) (2). Cross-source corroboration: README vs pyproject license conflict, internal prompt-count contradiction, and unverifiable 34-stack/31-guide lists within the supplied evidence (1). Fact/inference separation: the caveats section distinguishes confirmed behavior from expected degradation (2).
- The setup requires --dangerously-skip-permissions by default: 20–50 agents can modify, commit, and push your codebase with no per-action confirmation. Never run it against production repos or repos containing sensitive config without isolation.
- The license is not standard MIT: it carries a restrictive rider against OpenAI/Anthropic and their affiliates (no provision, hosting, benchmarking, or training use). Legal review is required before enterprise adoption; pyproject's MIT claim conflicts with the actual LICENSE.
- Automatic git push to origin can publish unreviewed agent-generated code to shared remotes; use --skip-commit or a dedicated review branch.
- Very high runtime cost: 20 parallel LLM agents with auto-restart by default and almost no cost guidance in the README; pilot small and set usage limits first.
- The coordination system is prompt-driven rather than code-enforced (the README states it is implemented entirely in the prompt file); its lock/conflict-prevention reliability is unverified without execution.
What does this agent do, and when should you use it?
Claude Code Agent Farm is a multi-agent orchestration framework written in Python 3.13 that runs up to 50 Claude Code agents in parallel (20 by default) inside a tmux session. The main script, claude_code_agent_farm.py, generates problem lists, launches agents in individual panes, monitors their health via heartbeat files and context-percentage parsing, and auto-restarts them on failure; the companion view_agents.sh script offers grid, focus, and split tmux viewing modes. It supports three workflows — bug fixing, best practices implementation, and cooperating multi-agent development — backed by 34 preconfigured tech-stack configs, 37 prompt templates, and 35 best practices guides. The cooperating workflow is implemented entirely through prompts: agents claim work via a JSON registry and lock files under a /coordination/ directory to avoid file conflicts. Runs produce HTML reports, and ~/.claude/settings. is automatically backed up and restored to guard against corruption.
End-to-end flow: 1) Runs the type-check, lint, and test commands defined in the config's problem_commands (e.g., cargo check, bun run type-check) to generate a combined problems file; 2) Launches agents one by one (staggered, default 10s) into a tmux session named claude_agents, each pane running Claude Code via the cc alias; 3) Agents pick random problem chunks (chunk_size dynamically adjusted) or work through best-practices guides in chunks, marking completed items [COMPLETED] to prevent duplication; 4) The Python orchestrator continuously monitors via heartbeat files (.heartbeats/agent*.heartbeat), context-percentage parsing, and tmux pane titles, auto-clearing context below a threshold (default 20%) and restarting errored or stalled agents (heartbeat stale >2 minutes) with exponential backoff; 5) Changes are git-committed (with --commit-every N for incremental commits), and Ctrl+R broadcasts /clear to all agents; 6) Each run ends with an agent_farm_report_*.html report, and monitor state is written to .claude_agent_farm_state. for external tools. In cooperating mode, agents coordinate via active_work_registry., planned_work_queue., and agent_locks/ lock files under /coordination/.
- Teams maintaining large Next.js or Python/FastAPI codebases that want to burn down a backlog of type-checker and linter errors in parallel
- Engineering teams on legacy-style codebases who want systematic modernization driven by the 35 best practices guides, with progress documents persisting across runs
- Advanced users running large-scale refactoring, type-hint coverage, or multi-faceted performance work on one codebase, suited to the cooperating-agents lock-based workflow
- Teams wanting automated cleanup on niche stacks like Solana, Unreal Engine, or Kubernetes AI inference, choosing from 34 preconfigured configs or writing custom JSON
- Ops engineers running unattended in CI/CD, using --no-monitor mode to launch agents headlessly
What are this agent's strengths and limitations?
- Lock files and [COMPLETED] markers solve the core parallel-conflict problem, letting 20+ agents work the same codebase without stepping on each other
- Mature context management: auto-clear below threshold, one-key Ctrl+R broadcast of /clear, adaptive idle timeout (3× median cycle time) and exponential-backoff restarts
- 34 preconfigured tech stacks plus custom JSON configs, with 37 prompt templates and 35 best practices guides ready out of the box
- Strong operability: doctor pre-flight checks, settings backup/rotation/restore, HTML run reports, and an externally readable state file
- The cc alias can point at any interactive coding CLI (OpenCode, Codex CLI); the orchestrator does not hardcode the claude binary
- Monitoring is deeply Claude Code-specific: readiness detection (the 'Welcome to Claude Code!' banner), context-percentage parsing, /clear resets, and usage-limit detection degrade or go inert with other CLIs
- Requires running with --dangerously-skip-permissions; agents can directly modify your codebase and execute commands, so the security risk must be self-assessed
- Each agent consumes ~500MB RAM, and 20+ parallel agents impose real hardware and API-quota costs
- Requires Python 3.13+ with a heavy runtime dependency set (tmux, uv, direnv, project toolchains), making environment setup nontrivial
- The cooperating-agents workflow is primarily designed around Python FastAPI/Postgres; other stacks require designing your own prompts
- GitHub shows license NOASSERTION; the actual license is MIT plus an OpenAI/Anthropic rider that should be reviewed before commercial use
How do you install or deploy this agent?
Prerequisites: Python 3.13+ (managed by uv), tmux, an installed and configured Claude Code (claude command), git, your project's tools (e.g., Bun, mypy, ruff), and optionally direnv.
git clone https://github.com/Dicklesworthstone/claude_code_agent_farm.git
cd claude_code_agent_farm
chmod +x setup.sh
./setup.shsetup.sh creates a Python 3.13 virtualenv, installs dependencies, configures the cc alias (alias cc="ENABLE_BACKGROUND_TASKS=1 claude --dangerously-skip-permissions"), and sets up direnv. Verify with claude-code-agent-farm doctor --path /path/to/project.
How do you use this agent?
Bug fixing: claude-code-agent-farm --path /path/to/project --config configs/nextjs_config.
Best practices: copy the guide first (cp best_practices_guides/NEXTJS15_BEST_PRACTICES.md /path/to/project/best_practices_guides/), then run claude-code-agent-farm --path /path/to/project --config configs/nextjs_best_practices_config.
Cooperating agents: claude-code-agent-farm --path /project --prompt-file prompts/cooperating_agents_improvement_prompt_for_python_fastapi_postgres.txt --agents 5
Quick test run (5 agents, skip git): claude-code-agent-farm --path /project -n 5 --skip-regenerate --skip-commitHeadless: add --no-monitor --auto-restart. Start with 5-10 agents first; each agent uses ~500MB RAM and the default cap is 50. CLI flags (--agents, --chunk-size, --context-threshold, --commit-every) override the JSON config.