DuoX — multi-peer AI CLI orchestrator (Claude + Codex + Ollama + OpenClaw). Shared transcript, parallel swarms, cross-checking, credit fallback, MCP, headless mode. By AbteeX AI Labs.
Project description
Claude Code · Codex · Ollama · OpenClaw — one terminal, one transcript.
A multi-peer AI CLI orchestrator with shared memory, cross-checking, parallel
swarms, MCP passthrough, and automatic credit fallback.
an AbteeX AI Labs release · site · github · huggingface space
DuoX is a drop-in CLI alternative to Claude Code / Codex CLI that runs them together — plus Ollama (local) and OpenClaw (inter-agent channels) — under one supervisor loop. One prompt, many peers, a shared transcript, a single scrolling interface.
Why DuoX?
| Claude Code | Codex CLI | DuoX | |
|---|---|---|---|
| Single-agent chat | ✓ | ✓ | ✓ |
| Multiple agents in one transcript | ✗ | ✗ | ✓ |
| Cross-validation (planner ↔ executor) | ✗ | ✗ | ✓ |
| Parallel sub-agent fan-out | ✗ | ✗ | ✓ |
| Automatic credit/rate-limit fallback | ✗ | ✗ | ✓ |
| Local Ollama fallback | ✗ | ✗ | ✓ |
| MCP pass-through | ✓ | ✗ | ✓ |
CLAUDE.md / AGENTS.md auto-context |
✓ | ✓ | ✓ |
@file mentions, /compact, /remember |
✓ | partial | ✓ |
Headless -p + JSON output |
✓ | ✓ | ✓ |
| HTTP API daemon | ✗ | ✗ | ✓ |
Install
pip install duox
From source:
git clone https://github.com/aimaghsoodi/duo && cd duo
pip install -e .
Requires Python 3.10+. After install:
duox init # write ~/.duo/config.toml + sample skill
duox doctor # verify peers, MCP, readline, openclaw
duox doctor tells you exactly what's missing and how to fix it.
Quick start
Interactive (default — Claude-Code-like loop):
duox
# then type your goal, or any of:
# /help /tips /examples /peers /cost /compact /remember /doctor
# @src/main.py (inline file excerpt)
# @src/main.py:40-80 (line range)
# /cd ../other-repo (switch working dir mid-session)
Headless (for scripts / CI / git hooks):
duox -p "summarise the last 10 commits"
duox -p "run the test suite and fix any failures" --output-format json
echo "review my changes" | duox -p
With specific peers / supervisor:
duox --peers claude,codex,ollama --supervisor claude "refactor the auth module"
duox --parallel "run these three benchmarks"
duox --resume abc123 # resume a previous session
Try it live
A Gradio demo of the orchestration loop is hosted on Hugging Face:
👉 https://huggingface.co/spaces/AbteeX-AI-Labs/duox
Features
- Shared transcript — every peer sees every message.
- Supervisor / executor loop — one peer plans & validates, others execute.
- Parallel swarm mode — fan the same task across peers, supervisor merges.
- Credit fallback — rate-limit/429/"out of credits" auto-fails over.
- Context files —
CLAUDE.md,AGENTS.md,DUO.mdauto-loaded (walks up from cwd). @filementions — inline file/dir/line-range excerpts in any prompt.- Skills — markdown prompts in
~/.duo/skills/auto-injected by keyword match. - Sessions — JSONL event log + transcript under
~/.duo/sessions/;duox --resume. - Hooks — run commands on
pre_step/post_step(tests, linters, formatters). - MCP pass-through —
[mcp.servers.*]in your config is forwarded to Claude. - HTTP API —
duox serve --port 8787exposes goals/sessions over JSON. - Per-project config — drop a
.duo.tomlin any repo to override globals. - Line editor — history,
↑/↓, tab-complete on slash commands + peer names. - 30+ slash commands —
/helplists them all.
Configuration
~/.duo/config.toml:
peers = ["claude", "codex", "ollama"]
supervisor = "claude"
ollama_model = "llama3.1"
max_steps = 30
parallel_default = false
[hooks]
pre_step = []
post_step = ["pytest -q"]
[mcp.servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
[openclaw]
thinking = "high"
Project-level .duo.toml in your repo root is deep-merged on top.
Headless / scripting
# Plain text (stdout = final answer)
duox -p "give me a release-notes draft"
# JSON envelope with per-peer stats
duox -p "audit this PR" --output-format json | jq '.final'
JSON output shape:
{
"ok": true,
"final": "…final answer…",
"session_id": "20260418-abc",
"turns": 14,
"peers": {"claude": {"calls": 4, "seconds": 12.3, "tokens_in": 4280, "tokens_out": 910}}
}
Architecture
user prompt
↓
supervisor ──► JSON decision {action, to, instructions}
│
├── delegate ─► executor peer(s) ─► output
│ │
│ └── (parallel) ─► merge
├── execute_self
├── validate
└── done ─► final answer
Under the hood: claude -p --dangerously-skip-permissions,
codex exec --dangerously-bypass-approvals-and-sandbox, ollama run, and
openclaw agent, streamed through a small Python orchestrator.
Note: the internal Python package is still named
duofor backwards compatibility —from duo import …continues to work. The user-facing CLI isduox, withduokept as a legacy alias.
Safety
DuoX runs peer CLIs with permissive flags so they can actually do work. Run it in a directory you trust — ideally a scratch repo, container, or VM. The transcript shows every action; read it.
Develop
pip install -e '.[test]'
pytest -q # 47 tests, 3 OS × 3 Python versions in CI
Links
- PyPI: https://pypi.org/project/duox/
- GitHub: https://github.com/aimaghsoodi/duo
- HF Space (demo): https://huggingface.co/spaces/AbteeX-AI-Labs/duox
- HF model card: https://huggingface.co/AbteeX-AI-Labs/duox
- Issues: https://github.com/aimaghsoodi/duo/issues
License
MIT © 2026 AbteeX AI Labs.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file duox-0.2.0.tar.gz.
File metadata
- Download URL: duox-0.2.0.tar.gz
- Upload date:
- Size: 40.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.11.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
cc110d36bcbe146467f4e5665b2888b4fc9691b49d75f58be17889d113474a45
|
|
| MD5 |
8b14a3eda4f2e88350c7685cf97601ab
|
|
| BLAKE2b-256 |
9902a282408b0caec1c6bf234f25b1614463f1d0c38b3db99ae4e91f6485ddd4
|
File details
Details for the file duox-0.2.0-py3-none-any.whl.
File metadata
- Download URL: duox-0.2.0-py3-none-any.whl
- Upload date:
- Size: 42.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.11.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
5265898de3e9650694a9457fa2791ee17ea7958e350cda6e29a4d805d8d8161d
|
|
| MD5 |
7a799b6199905897b68942c9d31e75a5
|
|
| BLAKE2b-256 |
b5ca70ba4fce2c03fffaee6923efa2d2c34ecd277513aa1c37d3ea26a6a1ce1d
|