agent-mux

One CLI, one JSON contract, any coding agent engine.

The original itch was simple: Claude Code, Codex, and Gemini CLI are all useful in different ways, but each one speaks its own little dialect. Different flags, different event streams, different timeout behavior, different recovery story. Great workers. Bad shared infrastructure.

agent-mux is the dispatch layer I keep between them. A coordinator can ask for one bounded job, choose a worker profile, pass a prompt, and get back a normalized result instead of babysitting three incompatible harnesses.

It started as a TypeScript bridge, then got rewritten in Go because the hard part was never string templating. The hard part was supervision: subprocess lifecycle, heartbeats, soft and hard timeouts, async jobs, durable artifacts, process-group cleanup, and recovering useful work after something times out mid-flight.

Current shape: prompt profiles live as markdown files with YAML frontmatter. The prompt is the worker. `-P=lifter` or `-P=auditor` resolves engine, model, effort, timeout, skills, and system prompt into one dispatch. CLI flags can still override the profile when the situation calls for it.

Every dispatch gets an artifact directory before the worker starts. The durable record lives under `~/.agent-mux/dispatches/`; runtime files carry `status.json`, `events.jsonl`, inbox messages, and worker-created artifacts. Job done is holy, but partial evidence is still evidence.

The part I care about most is not the CLI trick. It is the operating model: a main session stays thin, decides what matters, and sends bounded work to the right engine with the right skill bundle. Codex for implementation and audits. Claude for synthesis and planning. Gemini when a third model family is useful. Same caller contract across all of them.

This is also where skills became load-bearing. A worker should not receive a wall of repeated project lore every time. It should receive the task plus the exact operational runbooks it needs: web search, browser work, repo audit, writing, verification, whatever the job actually demands.

Status as of May 2026: public repo, Go rewrite active, async and recovery paths working, prompt profiles in daily use, and the older TypeScript version preserved on the `agent-mux-ts` branch. It is not the grand agent OS by itself. It is the boring dispatch organ that lets the rest of the system breathe.

Repo: buildoak/agent-mux. Related field notes: Codex Inside Claude Code. Subagents Inside Codex., the tennis autoresearch loop, robots v4, and flowers for dry Claude.