Codeband

Python 3.11+ License: MIT PyPI GitHub stars

Adversarial multi-model coding agents via Band.ai.

Codeband runs Claude Code and Codex in adversarial roles on the same repository: one model family writes code, the other reviews it before merge. The same pattern applies to planning: one model decomposes the task, the other validates the plan. The goal is to catch blind spots that same-model review can miss, while keeping every worker isolated in its own git worktree.

It is built for headless operation: local terminals, Linux servers, CI, Docker, and distributed cloud workers.

• Cross-model review by default: Claude-written PRs are routed to Codex reviewers, and Codex-written PRs are routed to Claude reviewers.
• A real orchestration loop: planner, plan reviewer, coders, code reviewers, mergemaster, and watchdog coordinate through Band.ai.
• Safe workspace isolation: each coder works in a separate git worktree and opens a PR.
• Risk-aware merging: low-risk PRs can auto-merge; medium, high, and critical changes wait for approval.
• Human-friendly and headless: use the interactive shell locally, or run the same orchestrator in CI and Docker.

Codeband's main advantage is not raw parallelism; it is adversarial pairing. A task is planned by one model family and reviewed by another, then code written by one model family is reviewed by the other. This catches model-specific blind spots better than asking one model to judge its own work.

Parallel coders are useful when the Planner can split a task into independent subtasks with little file overlap. Each coder gets its own git worktree and branch, so separate subtasks can run at the same time without sharing a working directory. Parallel planners and plan reviewers are useful mostly for throughput across multiple queued tasks; for one task, a single Planner plus one opposite-framework Plan Reviewer is usually enough.

The default configuration is the recommended shape: one Claude Coder, one Codex Coder, one Reviewer from each framework, one Planner, and one opposite-framework Plan Reviewer. You can scale pools with /scale in the shell or cb scale, then run cb setup-agents so Band.ai has matching agents.

For collision-free parallel review, keep opposite-framework reviewer capacity at least as large as coder capacity: Claude coders need Codex reviewers, and Codex coders need Claude reviewers. Today first-dispatch reviewer selection is prompt-enforced from the Worker Pool Roster using deterministic worker-index pairing; full code-backed arbitration is on the roadmap.

Codeband needs these in every deployment mode:

1. Python 3.11+ The package installs the cb and codeband commands.

2. Band.ai account Used for agent communication and orchestration.

3. Claude authentication Required for Claude agents. Defaults to an Anthropic API key (ANTHROPIC_API_KEY); a Claude Pro/Max subscription is an explicit opt-in via claude.auth_mode: subscription (see Authentication). Codeband shells out to the claude CLI.

4. Codex/OpenAI authentication Required if you use Codex agents. The default config does, so set OPENAI_API_KEY or log in with Codex locally. Codeband shells out to the codex CLI.

5. Git tooling Codeband uses git for worktrees, branches, pushes, and fetches. Install gh if you want PR and issue workflows.

cb doctor

Run cb doctor after setup. It checks credentials, installed tools, config files, Band.ai connectivity, and the memory backend.

Start with local mode unless you already know you need container isolation or multiple machines.

Use this when you are trying Codeband, developing locally, or running small jobs on one machine.

cb # interactive shell
cb run # same orchestrator, no UI

All agents run in one Python process. They still get isolated git worktrees, but they share your local environment and credentials.

Use this when you want each agent in its own container, or when running on a server or CI machine.

cb up
cb up --detach

Docker mode still runs on one host. Containers share Docker volumes for the workspace. Put API keys or long-lived tokens in .env; containers cannot read the host macOS Keychain.

Use this when you want agents on separate VMs, cloud providers, or hosts.

cb run --agent conductor
cb run --agent coder-claude_sdk-0
cb run --agent reviewer-codex-0
cb --attach

Each agent has its own clone of the repository. Agents coordinate through Band.ai WebSocket and memory, and code moves through the Git remote with push and fetch.

Distributed mode requires paid Band.ai memory. On free-tier Band.ai, use local or Docker mode on one machine.

uv tool install codeband # or: pipx install codeband / pip install codeband
cd my-project
cb init --repo https://github.com/myorg/myrepo.git
cp .env.example .env

We recommend uv tool because it auto-manages the Python toolchain and installs codeband into its own isolated venv, avoiding conflicts with other tools in your environment. pipx install codeband is the equivalent pre-uv option. Plain pip install codeband also works if you are installing into an existing venv you manage. Don't have uv? Install it from astral.sh/uv (one-liner curl) and run uv tool update-shell once so cb lands on your PATH.

Edit .env:

BAND_API_KEY=band_u_...
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

Then register agents, verify setup, and start the shell:

cb setup-agents
cb doctor
cb

Inside the shell:

> /task Add JWT authentication with tests
> /status
> /diff coder-claude_sdk-0
> /pending
> /approve 42

Slash commands take the rest of the line as their argument, so /task Add JWT authentication with tests does not need quotes. In a normal terminal command, quote multi-word descriptions: cb task "Add JWT authentication with tests".

On free-tier Band.ai, cb setup-agents may not be available. Create the eight default agents manually and write agent_config.yaml; the exact keys are documented in Configuration.

For credential precedence, Docker auth, and subscription-vs-API-key behavior, see Authentication.

cb # interactive shell
cb run # headless local orchestrator
cb up --detach # Docker stack
cb task "Fix flaky login tests" # send work to the Conductor
cb prs --sort smallest # browse open PRs
cb issues --label bug # browse open issues
cb issue 42 # send a specific issue
cb feed --no-thoughts # live activity stream
cb status # current task pipeline
cb diff coder-claude_sdk-0 # inspect a worker's changes
cb pending # PRs awaiting approval
cb approve 42 # approve and merge
cb usage # token usage and cost summary

Inside the shell, use slash commands: /task, /prs, /issues, /issue, /status, /diff, /pending, /approve, /reject, /log, /usage, /scale, /doctor, /help, and /quit.

Default local topology:

User task
 |
 v
Conductor
 |
 +--> Claude Planner ----> Codex Plan Reviewer
 |
 +--> Claude Coder -----> Codex Code Reviewer ----+
 | |
 +--> Codex Coder -----> Claude Code Reviewer ---+--> Mergemaster
 |
 +--> Watchdog

The default config uses eight Band.ai agents: Conductor, Mergemaster, one Planner, one Plan Reviewer, two Coders, and two Reviewers. The Watchdog is an in-process daemon and does not consume a Band.ai agent seat.

For the full design, see ARCHITECTURE.md.

• Authentication
• Configuration
• Troubleshooting
• Deployment
• Architecture
• Migration: v0 to v1
• Changelog

Codeband is alpha software. The current architecture is prompt-driven: agents follow structured prompts, and the Conductor relies on model context plus memory state to track protocol progress. The roadmap is to move more protocol state and branch enforcement into deterministic Python code.

Pool scaling is supported, but first-dispatch worker arbitration is still prompt-enforced. For best results, scale coders and their opposite-framework reviewers together, keep planner/plan-reviewer pools small, and avoid configurations where several coders must share one reviewer unless you are comfortable with queued or overlapping review turns.

Current planned work:

• Code-backed protocol state
• Deterministic Conductor state machine
• Code-backed branch enforcement
• Protocol acknowledgment states
• Python merge helpers
• Feedback-driven framework routing
• Room and task tagging in Band.ai

Contributions are welcome. Start with CONTRIBUTING.md, and please open an issue before large behavior changes.

git clone https://github.com/thenvoi/codeband.git
cd codeband
pip install -e ".[dev]" # or: uv pip install -e ".[dev]"
pytest
ruff check src/ tests/

Codeband is released under the MIT License.