Metadata-Version: 2.4
Name: agent-conductor
Version: 0.3.2
Summary: Run Codex CLI and OpenCode CLI simultaneously on isolated git worktrees - LLM task planner, parallel headless runners, auto-merge
Author: Anuj Mhatre
License: MIT
Project-URL: Homepage, https://github.com/a18-n03/agent-conductor
Project-URL: Repository, https://github.com/a18-n03/agent-conductor
Keywords: ai-agents,multi-agent,codex,opencode,orchestrator,llm,git-worktree
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-dotenv>=1.0
Requires-Dist: openai>=1.40
Dynamic: license-file

# Agent Conductor ⚡

[![PyPI](https://img.shields.io/pypi/v/agent-conductor?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/agent-conductor/)
[![Python](https://img.shields.io/pypi/pyversions/agent-conductor)](https://pypi.org/project/agent-conductor/)
[![License](https://img.shields.io/pypi/l/agent-conductor)](LICENSE)

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

```bash
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

```bash
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.

![Web UI](images/webui.png)

## Real run (claude + opencode, parallel)

![Conductor report](images/report_terminal.png)

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):**

```bash
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):**

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

**From source:**

```bash
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

```bash
# 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](https://github.com/openai/codex) (`npm i -g @openai/codex`)
  - [OpenCode CLI](https://opencode.ai) (`npm i -g opencode-ai`)
  - [Claude Code](https://claude.com/claude-code) (`npm i -g @anthropic-ai/claude-code`)
- An OpenAI-compatible API key for the planner (default: OpenCode Zen — free)
- Optional: [OmniRoute](https://github.com/diegosouzapw/OmniRoute) (`npm i -g omniroute`)
  — free gateway so any of the CLIs run on free models

## Model setup (tested working)

| Agent spec | Routes to | Needs |
|---|---|---|
| `codex` | your ChatGPT plan via Codex | codex login |
| `codex@omniroute/auto` | OmniRoute gateway → free models | omniroute serve + `OMNIROUTE_API_KEY` in `.env` |
| `opencode` | OpenCode default model | opencode auth |
| `opencode@opencode/x-preview-f-free` | ox-alpha (free) | nothing |
| `opencode@opencode/glm-5` | GLM-5 via OpenCode Zen | OpenCode Zen billing |
| `claude` | Claude Code default (Anthropic plan or `ANTHROPIC_MODEL`) | claude login / env |
| `claude@auto/best-coding` | OmniRoute → free Claude routing | `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN` env |

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

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

## Usage

```bash
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

| Module | Role |
|---|---|
| `src/planner.py` | LLM splits goal into 2 file-disjoint workstreams with an interface contract |
| `src/worktrees.py` | git worktree + branch lifecycle, base commit handling |
| `src/runners.py` | Parallel headless runners (threads), live logs, per-agent timeouts |
| `src/merger.py` | Branch merging with conflict abort + final report |

## 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:

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

---

<div align="center">
<sub>Built by <a href="https://github.com/a18-n03">Anuj Mhatre</a> · BTech CSE (AI & ML)</sub>
</div>
