Metadata-Version: 2.4
Name: agent-conductor
Version: 0.1.0
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 ⚡

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

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.

## Install

**From PyPI** (once published):

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

## How it works

```
you: python conductor.py "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 …
      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` and `opencode run --dir <dir>`
- **Merge:** branches merged back to `main` automatically; conflicts are aborted and reported

## Requirements

- Python 3.10+
- [Codex CLI](https://github.com/openai/codex) (`npm i -g @openai/codex`)
- [OpenCode CLI](https://opencode.ai) (`npm i -g opencode-ai`)
- 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 Codex runs without a ChatGPT Plus plan

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

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>
