agent-mux

Cross-harness dispatch layer. One CLI, one JSON contract, any LLM engine.

Go rewrite. agent-mux was recently rewritten from TypeScript to Go — static binary, goroutine-based supervision, no runtime dependencies.
The TS version is preserved on the agent-mux-ts branch.
See DOCS.md for the full technical reference.

What It Does

AI coding harnesses (Codex, Claude Code, Gemini CLI) are powerful but isolated — each has its own CLI flags, event format, sandbox model, and session lifecycle. agent-mux connects them: any LLM can dispatch work to any other LLM through one JSON contract and one config system. Roles, variants, and pipelines turn good dispatch patterns into reusable TOML config.

Core Principles

1. Tool, not orchestrator. The calling LLM decides what to do. agent-mux handles the how.
2. Job done is holy. Artifacts persist across timeout and process death. Every dispatch has an artifact path.
3. Errors are steering signals. Every error tells the caller what failed, why, and what to try next.
4. Single-shot with curated context. One well-prompted dispatch beats a swarm of under-specified workers.
5. Config over code. Roles, pipelines, models, timeouts — all TOML. The binary is generic.
6. Simplest viable dispatch. CLI call > config > code. Escalate only when needed.

Quick Start

git clone https://github.com/buildoak/agent-mux && cd agent-mux
go build -o agent-mux ./cmd/agent-mux

Minimal dispatch (JSON via --stdin — the canonical invocation pattern):

printf '{"engine":"codex","prompt":"Review src/core.go for timeout edge cases","cwd":"/repo"}' \
  | ./agent-mux --stdin

Role-based dispatch (engine, model, effort, timeout resolved from config.toml):

printf '{"role":"scout","prompt":"Find all usages of deprecated API","cwd":"/repo"}' \
  | ./agent-mux --stdin

Dispatch output is always a single JSON object on stdout. Lifecycle subcommands (list, status, result, inspect, gc) default to human-readable but accept --json. The config subcommand (config, config roles, config pipelines, config models) introspects the fully-resolved configuration without dispatching. stderr carries NDJSON event stream and heartbeat lines.

Configuration

Roles, models, pipelines, and timeouts live in .agent-mux/config.toml alongside a prompts/ directory for system prompt files.

Resolution order (later wins): ~/.agent-mux/config.toml (global) → ~/.agent-mux/config.local.toml (global machine-local) → <cwd>/.agent-mux/config.toml (project) → <cwd>/.agent-mux/config.local.toml (project machine-local) → --config (explicit). Project config merges on top of global with defined-wins semantics — set fields override, absent fields inherit. config.local.toml files are for per-machine overrides and should be gitignored.

Minimal role definition:

[roles.scout]
engine = "codex"
model = "gpt-5.4-mini"
effort = "low"
timeout = 180
system_prompt_file = "prompts/scout.md"

Dispatch: {"role":"scout","prompt":"Find all TODO comments","cwd":"/repo"}

Setup Guide — first-time walkthrough, roles, variants, pipelines.
TOML Reference — full schema, every field, merge semantics.

Engines

Engine CLIs must be installed separately — agent-mux dispatches to them, it does not bundle them.

Features

• Role-based dispatch — Roles resolve engine, model, effort, timeout, skills, and system prompt from TOML config. One field replaces six flags.
• Variant system — Swap engines within a role while keeping the same semantics. {"role":"lifter","variant":"claude"} runs a lifter with Claude instead of Codex.
• Pipeline orchestration — Multi-step chains, fan-out parallelism, and handoff rendering between steps. Defined in TOML, not code.
• Recovery and signals — Continue timed-out work with --recover. Steer live dispatches with inbox signals.
• Two-phase timeout — Soft timeout fires a wrap-up signal, grace period allows clean exit, hard timeout kills. Artifacts are preserved at every phase.
• Event streaming — 15 NDJSON event types on stderr: dispatch_start, heartbeat, tool_start, tool_end, file_write, timeout_warning, and more.
• Hooks — Pattern-based deny/warn rules evaluated on harness events. Safety preamble injection.
• Profiles and coordinators — Load orchestrator personas from markdown specs with frontmatter-driven defaults.
• Skill injection — Load SKILL.md runbooks into the dispatch prompt. Skills carry scripts, references, and setup.
• Liveness supervision — 5-second watchdog cycle detects hung harnesses. Process-group signals ensure grandchildren die with the harness.
• Artifact-first design — Artifact directory created before the harness starts. ScanArtifacts() runs on every terminal state.

Authentication

Both Codex and Claude support subscription-based OAuth as a fallback when no
API key is set. agent-mux will attempt dispatch if any auth path is available —
MISSING_API_KEY is a warning, not a hard failure.

Anthropic ToS compliance: The claude engine uses Claude Code SDK with
your API key (ANTHROPIC_API_KEY) — this is the fully compliant path. Device
OAuth (subscription login) falls under Anthropic's Consumer ToS §3.7 which
restricts automated/scripted access outside the API. Always use
ANTHROPIC_API_KEY for the claude engine in automated workflows.

Documentation

License

MIT