Claude Code Agent Farm: Running 20+ Parallel AI Coding Agents With tmux

What Claude Code Agent Farm Does and Who It Is For

Running a single Claude Code session on a large codebase means one agent working through one file at a time, with no parallelism and a context window that fills up during long runs. For codebases with many independent bugs or with a best-practices guide that needs systematic application, this is slow.

claude_code_agent_farm solves this by orchestrating multiple Claude Code sessions simultaneously. Each agent runs in its own tmux pane, receives a prompt from a JSON config, works on its assigned portion of the codebase, and commits its results to git with rich diff summaries. A lock-based coordination system prevents agents from modifying the same file at the same time.

The default configuration runs 20 agents simultaneously. The README states that up to 50 agents can run with the max_agents configuration setting. The target user is a developer or engineering team that already uses Claude Code and wants to apply it at a scale that a single session cannot reach efficiently. The framework is not intended as a first AI coding tool; it assumes Claude Code is installed, configured, and working before setup begins.

Prerequisites and the cc Alias That Everything Depends On

The framework requires Python 3.13 or later (managed by uv), tmux, the claude command (Claude Code), git, and the project's own build tools depending on the tech stack. The setup script handles most of this automatically, but the key prerequisite is a specific shell alias:

alias cc="ENABLE_BACKGROUND_TASKS=1 claude --dangerously-skip-permissions"

The orchestrator types 'cc' into each tmux pane. It does not hardcode the claude binary, which means the alias can be pointed at a different agent CLI. The README shows two examples:

alias cc="npx -y opencode-ai@latest"
alias cc="npx -y @openai/codex"

Using a non-Claude CLI degrades the framework's monitoring capabilities. Agent readiness detection, context-percentage parsing, the /clear broadcast, usage-limit detection, and settings backup checks all assume Claude Code's specific output format. The framework still launches and works with other CLIs, but health checks and context management are inert.

The setup script automatically configures the cc alias and detects and patches common mis-quotings in existing alias definitions. It handles both bash and zsh shells.

Setup, Pre-Flight Check, and Shell Completion

After cloning the repository:

git clone https://github.com/Dicklesworthstone/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, installs dependencies, configures the cc alias, and sets up direnv for automatic environment activation. It handles both bash and zsh, validates existing alias definitions, and patches common mis-quoting patterns in an existing .bashrc or .zshrc. After setup, the pre-flight check verifies the environment against a target project:

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

The doctor command checks Python version, tmux, git, Claude Code configuration and API keys, project-specific tool availability, and file permissions. It reports each check's outcome and identifies any missing prerequisites before an agent run starts. The README recommends running doctor before every new project run, not just the first time, because tool availability can differ between projects.

Shell completion can be installed for faster command entry:

claude-code-agent-farm install-completion --shell zsh

Bash and fish are also supported. The framework is installed as a Python package with the entry point claude-code-agent-farm, defined in pyproject.toml. It depends on typer for the CLI and rich for terminal output.

Running the Two Primary Workflows: Bug Fixing and Best Practices

The framework supports two main workflow types through separate JSON configuration files.

For bug fixing, point the framework at a project and a config:

claude-code-agent-farm --path /path/to/project --config configs/nextjs_config.json
claude-code-agent-farm --path /path/to/project --config configs/python_config.json

Each config describes how to find bugs, what constraints the agents operate under, and how many agents to run. The configs/ directory ships with configurations for multiple tech stacks.

For best-practices sweeps, the process starts by placing the relevant guide into the project:

cp best_practices_guides/NEXTJS15_BEST_PRACTICES.md /path/to/project/best_practices_guides/
claude-code-agent-farm --path /path/to/project --config configs/nextjs_best_practices_config.json

The best_practices_guides/ directory contains pre-written guides. Agents read the guide, identify violations in their assigned code sections, and apply fixes. Progress is tracked in HTML run reports and committed to git.

The context management system handles long runs: agents automatically clear their own context when it nears the limit, and pressing Ctrl+R broadcasts /clear to all agent panes simultaneously.

Lock-Based Coordination and Real-Time Monitoring

With 20 or more agents working on the same codebase, file conflicts are a real risk. The framework uses a file-locking system to prevent two agents from modifying the same file at the same time. Each agent acquires a lock before editing, holds it during its changes, and releases it when done. The README describes this as an advanced lock-based system that enables safe concurrent work.

The real-time dashboard shows context usage warnings, heartbeat tracking per agent, and tmux pane titles that summarize each agent's current state. Multiple tmux viewing modes are supported; the README lists them as options for operators who want different layouts for monitoring the running farm. This gives operators a view of the farm's health without switching to individual panes.

The auto-recovery system restarts agents when they become idle for longer than an adaptive timeout. The idle timeout adapts based on observed work patterns in the current run rather than using a fixed value, which avoids premature restarts on slow operations and unnecessary delays on fast ones. Agents that hit Claude Code usage limits trigger detection logic that pauses and waits rather than failing silently. Settings backup uses size-based rotation with atomic writes, which protects against corrupted settings files during an unexpected crash.

Shutdown is handled gracefully: pressing Ctrl+C once begins an orderly shutdown. Pressing Ctrl+C twice within three seconds force-kills all remaining panes immediately. The CHANGELOG.md in the repository tracks version history for users who want to review changes between updates.

34 Technology Stacks and Modular Setup Scripts

The tool_setup_scripts/ directory contains 24 setup scripts for different development environments. Running the interactive menu:

cd tool_setup_scripts
./setup.sh

Shows the available scripts. Named examples include setup_python_fastapi.sh (Python 3.12+, uv, ruff, mypy, pre-commit), setup_go_webapps.sh (Go 1.23+, golangci-lint, air, migrate, mockery), setup_nextjs.sh (Node.js 22+, Bun, pnpm, TypeScript, ESLint, Prettier), setup_rust.sh (Rust toolchain plus cargo tools), and setup_java_enterprise.sh (Java 21 LTS, SDKMAN, Gradle, Maven, JBang). These ensure the project's tools are available before agent runs begin.

Comparing to Aider, a well-known single-session open-source AI coding tool: Aider runs conversationally, letting a developer interact with a model through a terminal to apply edits to specified files. It works well for interactive, targeted changes. The agent farm runs headlessly across the entire codebase in parallel, with no interaction during a run. The two approaches suit different work modes: Aider for focused, developer-guided changes; the agent farm for systematic, breadth-first improvements at scale.

The last push to the repository was on 2026-09-21. The repository has no GitHub releases. GitHub's license detection returns NOASSERTION for this repository; the pyproject.toml declares MIT. Teams with licensing requirements should verify the LICENSE file directly.

Editorial conclusion

Claude Code Agent Farm is a good fit for codebases where a single agent session runs too slowly or times out, where bugs are sufficiently independent to be parallelized, or where a best-practices guide needs systematic application across many files. It is not suitable as a first AI coding tool: it assumes Claude Code is already configured and working, and it requires tmux, Python 3.13, and uv. The license in GitHub's detection is NOASSERTION; the pyproject.toml claims MIT, but teams with legal requirements should review the LICENSE file directly before incorporating the framework.

Frequently asked questions

Official sources

1. Dicklesworthstone/claude_code_agent_farm on GitHub
2. Issues
3. README