code-swarm

code-swarm is a single-machine coding-agent runner. It bootstraps a target repo, plans scoped tasks, runs builders in isolated git worktrees, verifies their changes, and reconciles failures until the repo is healthy or progress stops.

It works against either:

• a managed local vLLM server
• an external OpenAI-compatible endpoint such as OpenRouter

Install

uv pip install --system -e '.[dev]'
uv run pytest -q tests -m 'not live_e2e'

Quick Start

1. Create a config.

cp swarm.example.toml swarm.toml

2. Point repo_path, workspace_root, and state_db_path at real locations.

3. Validate the model endpoint.

code-swarm check-model --config swarm.toml

4. Start a run.

code-swarm start-run --config swarm.toml \
  --request "Create a Python CLI that converts temperatures between Celsius and Fahrenheit with tests"

5. Watch the run.

code-swarm show-run --config swarm.toml --run-id 1 --watch

Common Workflows

Bootstrap a config interactively

code-swarm bootstrap --config swarm.toml

Start local serving

code-swarm serve-model --config swarm.toml

Managed mode expects:

• vllm in PATH
• a supported GPU
• HF_TOKEN set for model downloads

Use an external endpoint

[model]
profile = "custom"
thinking_default = "off"
api_key_env = "OPENROUTER_API_KEY"
timeout_seconds = 300.0

[serving]
mode = "external"
endpoint_url = "https://openrouter.ai/api/v1"
served_model_name = "google/gemini-2.5-flash"

With mode = "external", endpoint_url is used directly and local vLLM checks are skipped.

Resume or inspect a run

code-swarm resume-run --config swarm.toml --run-id 1
code-swarm show-run --config swarm.toml --run-id 1
code-swarm dashboard --config swarm.toml --run-id 1
code-swarm cleanup-run --config swarm.toml --run-id 1

Max mode

code-swarm start-run --config swarm.toml --request "..." --max --max-waves 15

Max mode chains multiple runs. After each completed wave, a feature agent inspects the repo and generates the next prompt.

Configuration

Start from swarm.example.toml.

Important top-level fields:

• repo_path: target repository
• workspace_root: root for builder worktrees
• state_db_path: SQLite state database
• verification_commands: commands that define project health
• skip_setup: when true, setup is disabled and verification_commands must already be configured
• max_concurrent_builders: max parallel builders

Important [model] fields:

• profile: built-in profile name or custom
• thinking_default: on or off
• api_key_env: env var holding the API key
• timeout_seconds: per-request HTTP timeout

Important [serving] fields:

• mode: managed or external
• served_model_name: model name expected from the endpoint
• endpoint_url: explicit API base URL for external mode
• host and port: managed local endpoint settings

Pipeline

The orchestrator runs this loop:

1. Setup agent prepares the repo or repairs environment issues.
2. Root planner emits top-level tasks.
3. Subplanners decompose broad tasks when needed.
4. Builders work in isolated git worktrees.
5. Merge gate cherry-picks and re-verifies passing work.
6. Reconciler emits fix tasks when verification or merge fails.
7. Finalization stops when the repo is healthy or no more progress is possible.

Greenfield repos with specs/tests but no implementation can start with a single repo-wide bootstrap builder task.

Project Layout

src/code_swarm/
  cli.py            CLI entrypoint
  config.py         TOML loading and validation
  orchestrator.py   main run loop
  planner.py        root planner, subplanner, reconciler
  builder.py        builder agent loop
  setup_agent.py    initial and reactive environment setup
  verification.py   baseline and project verification
  merge.py          merge gate
  ecosystem.py      ecosystem detection and command resolution
  state.py          SQLite state store
  serving.py        model endpoint and vLLM utilities
  tools.py          planner/builder/setup tool executors
  dashboard.py      Textual dashboard
  tui.py            Rich watch view
  prompts/          agent system prompts

tests/              unit and scripted end-to-end coverage
docs/               architecture notes and known issues
showcase/           example generated projects

Testing

Fast core checks:

uv run pytest -q tests/test_cli.py tests/test_config.py tests/test_repo.py

Full non-live suite:

uv run pytest -q tests -m 'not live_e2e'

Live end-to-end coverage requires a real API key and is marked with live_e2e.

Notes

• Setup runs automatically on empty repos or when verification commands are missing, unless skip_setup = true.
• Verification commands are canonicalized so merge/finalization checks run full-suite commands instead of narrow file-specific variants when the ecosystem is recognized.
• See docs/ARCHITECTURE.md for module-level details and docs/KNOWN-ISSUES.md for current limitations.