agent-conductor

Agent Conductor ⚡

Run Codex CLI, OpenCode CLI and Claude Code simultaneously on the same project — frontend and backend in parallel, zero file conflicts.

pip install agent-conductor
agent-conductor "build a weather app: React frontend, FastAPI backend"

One command splits your goal into two independent workstreams, gives each agent its own isolated git worktree, runs both CLIs headlessly at the same time, and merges the work back.

🖥️ Web UI

pip install fastapi uvicorn
uvicorn webui:app --port 8600

Open http://localhost:8600 — type a goal, pick your agents, hit Run, watch both agents work live in the terminal panel.

Real run (claude + opencode, parallel)

Merged output passed a live endpoint test: GET /api/quote → {"author": "Lao Tzu", "quote": "The journey of a thousand miles..."}

Install

npm (any OS, any folder — auto-creates its own Python venv):

npm install -g @anujmau/agent-conductor
agent-conductor "build a todo app: React frontend, FastAPI backend"

Requires Python 3.10+ on the machine. The npm package bundles the Python source, creates an isolated venv on install, and runs from YOUR current directory (.env and generated projects/ live in whatever folder you run it from).

pip (Python users):

pip install agent-conductor
agent-conductor "build a todo app: React frontend, FastAPI backend"

From source:

git clone https://github.com/a18-n03/agent-conductor
cd agent-conductor
pip install -e .
cp .env.example .env        # add ZEN_API_KEY (planner) + OMNIROUTE_API_KEY (codex via gateway)

Examples

# default: Codex + OpenCode
agent-conductor "build a todo app: React frontend, FastAPI backend"

# Codex (via OmniRoute, free) + ox-alpha (free) - the proven combo
agent-conductor "build a joke app: static HTML frontend, FastAPI backend" \
  --agents "codex@omniroute/auto,opencode@opencode/x-preview-f-free"

# Claude + OpenCode
agent-conductor "landing page + contact API" \
  --agents "claude@auto/best-coding,opencode@opencode/x-preview-f-free"

# custom project dir + timeout
agent-conductor "build a scraper + dashboard" --dir C:\dev\myproject --timeout 20

How it works

you: python agent-conductor "build a todo app: React frontend, FastAPI backend"
                          |
              [1] LLM PLANNER (splits goal into 2 isolated workstreams)
                          |
        ┌─────────────────┴──────────────────┐
        ▼                                    ▼
  [2] git worktree                    [2] git worktree
      .conductor/codex-…                  .conductor/opencode-…
        ▼                                    ▼
  [3] codex exec …                    [3] opencode run …  (or claude -p …)
      frontend/ (parallel)                backend/ (parallel)
        ▼                                    ▼
        └────────────► [4] MERGE ◄───────────┘
                          |
                  [5] REPORT (commits, timings, conflicts)

• Isolation: each agent works in its own git worktree + branch → it physically cannot touch the other agent's files
• Contract: the planner writes a shared interface contract (API endpoints/types) into both prompts so the two halves fit together
• Headless: uses codex exec -C <dir> -s workspace-write, opencode run --dir <dir> and claude -p with per-agent model overrides
• Merge: branches merged back to main automatically; conflicts are aborted and reported

Requirements

• Python 3.10+
• At least TWO of these CLIs installed and authenticated:
  • Codex CLI (npm i -g @openai/codex)
  • OpenCode CLI (npm i -g opencode-ai)
  • Claude Code (npm i -g @anthropic-ai/claude-code)
• An OpenAI-compatible API key for the planner (default: OpenCode Zen — free)
• Optional: OmniRoute (npm i -g omniroute) — free gateway so any of the CLIs run on free models

Model setup (tested working)

For the OmniRoute path, add this block once to ~/.codex/config.toml:

[model_providers.omniroute]
name = "OmniRoute"
base_url = "http://localhost:20128/v1"
wire_api = "responses"
env_key = "OMNIROUTE_API_KEY"

Usage

pip install -r requirements.txt
cp .env.example .env        # add ZEN_API_KEY (planner) + OMNIROUTE_API_KEY (codex via gateway)

# ox-alpha frontend + ox-alpha backend (two free instances)
python conductor.py "build a joke app: static HTML frontend, FastAPI backend" \
  --agents "opencode@opencode/x-preview-f-free,opencode@opencode/x-preview-f-free"

# Codex (via OmniRoute) frontend + ox-alpha backend
python conductor.py "build a joke app: static HTML frontend, FastAPI backend" \
  --agents "codex@omniroute/auto,opencode@opencode/x-preview-f-free"

# default: your Codex plan + OpenCode default
python conductor.py "build a todo app"

What you get

  CONDUCTOR REPORT
  [OK ] codex      frontend             done (6.2 min)
  [OK ] opencode   backend              done (4.8 min)
  [OK ] merge      conductor/codex-frontend      merged
  [OK ] merge      conductor/opencode-backend    merged

Full agent transcripts land in logs/ — every tool call both agents made.

Architecture

Notes & limits

• Two agents is the sweet spot; more agents = more merge risk
• Agents can't see each other mid-run — that's a feature (isolation), the interface contract in their prompts is what keeps the halves compatible
• Conflicts are intentionally aborted, never auto-resolved — you decide

Proven result

Real run on this machine (2026-08-25): Codex (via OmniRoute, free models) built the frontend in 4.0 min while OpenCode (ox-alpha, free) built the backend in 0.7 min — in parallel, zero conflicts. Merged app passed a live endpoint test:

{"joke": "What does a cloud wear under its raincoat? Thunderwear."}

---