---

name: agent-mux description: | Unified subagent dispatch layer for Codex, Claude Code, and OpenCode engines. Spawn workers, run parallel execution pipelines, and get one strict JSON output contract. Use this skill when you need to: dispatch a subagent, spawn an agent worker, run multi-model pipelines, invoke codex/claude/opencode engines, or coordinate parallel execution across AI coding engines. Covers unified output parsing, timeout/heartbeat behavior, skill injection, and MCP cluster configuration. Keywords: subagent, dispatch, worker, codex, claude, opencode, parallel execution, multi-model, spawn agent, engine, unified output.

agent-mux

One CLI for Codex, Claude, and OpenCode with one strict JSON contract.

agent-mux --engine <codex|claude|opencode> [options] "prompt"

If agent-mux is not linked globally, run bun run src/agent.ts ... from this repo.

---

Setup

git clone https://github.com/buildoak/agent-mux.git /path/to/agent-mux
cd /path/to/agent-mux && ./setup.sh && bun link

• Claude Code: copy this repo into .claude/skills/agent-mux/
• Codex CLI: append this SKILL.md content to your project's root AGENTS.md

For the full installation walkthrough (prerequisites, verification, troubleshooting), see references/installation-guide.md.

---

Quick Reference

# Codex: implementation, debugging, concrete code changes
agent-mux --engine codex --cwd /repo --reasoning high --effort high "Implement retries in src/http/client.ts"

# Codex Spark: fast grunt work and broad scan/edit tasks
agent-mux --engine codex --model gpt-5.3-codex-spark --cwd /repo --reasoning high "Add doc comments across src/"

# Claude: architecture, reasoning, synthesis
agent-mux --engine claude --cwd /repo --effort high --permission-mode bypassPermissions "Design rollout plan for auth refactor"

# OpenCode: third opinion, model diversity, cost-flexible checks
agent-mux --engine opencode --cwd /repo --model kimi "Review this patch and challenge assumptions"

# Skill injection (repeatable)
agent-mux --engine codex --cwd /repo --skill react --skill test-writer "Implement + test dark mode"

# MCP clusters
agent-mux --engine claude --cwd /repo --mcp-cluster knowledge "Find canonical docs for token rotation"

# --browser sugar for browser cluster
agent-mux --engine codex --cwd /repo --browser "Open app, inspect controls, summarize findings"

# Full access mode
agent-mux --engine codex --cwd /repo --full "Install deps and implement requested fix"

# System prompt from file
agent-mux --engine claude --cwd /repo --system-prompt-file prompts/reviewer.md "Review this patch"

# Coordinator persona
agent-mux --engine codex --cwd /repo --coordinator reviewer "Audit this change for regressions"

# Combine coordinator + extra skill + inline system prompt
agent-mux --engine claude --cwd /repo --coordinator reviewer --skill perf-auditor --system-prompt "Prioritize latency risks." "Evaluate this service update"

---

Engine Selection Protocol

Use this decision tree:

1. Code execution, file edits, implementation -> Codex with --reasoning high.
2. Fast grunt work, filesystem scanning, parallel worker throughput -> Codex Spark with --model gpt-5.3-codex-spark.
3. Architecture, deep reasoning, multi-file analysis, synthesis, writing -> Claude.
4. Model diversity, third-opinion checks, cost-flexible runs -> OpenCode.

Note: Pratchett-OS coordinator uses Codex + Claude only.

For engine-specific prompting tips, model variants, and comparison tables, see references/prompting-guide.md.

---

CLI Flags

Source of truth: src/core.ts (parseCliArgs) + src/types.ts.

Common (all engines)

| Flag | Short | Type | Values | Default | Notes | | --- | --- | --- | --- | --- | --- | | --engine | -E | string | codex, claude, opencode | required | Engine selector | | --cwd | -C | string | path | current directory | Working directory | | --model | -m | string | model id | engine default | Model override | | --effort | -e | string | low, medium, high, xhigh | medium | Effort level | | --timeout | -t | string | positive integer (ms) | effort-mapped | Hard timeout override | | --system-prompt | -s | string | text | unset | Appended system context | | --system-prompt-file | -- | string | path to file | unset | Loads file as system prompt, joined with other prompts | | --coordinator | -- | string | coordinator name | unset | Loads spec from <cwd>/.claude/agents/<name>.md | | --skill | -- | string[] | repeatable names | [] | Loads <cwd>/.claude/skills/<name>/SKILL.md | | --mcp-cluster | -- | string[] | repeatable names | [] | Enables MCP cluster(s) | | --browser | -b | boolean | true/false | false | Adds browser cluster | | --full | -f | boolean | true/false | false | Full access mode | | --version | -V | boolean | true/false | false | Print version | | --help | -h | boolean | true/false | false | Print help |

Codex-specific

| Flag | Short | Type | Values | Default | Notes | | --- | --- | --- | --- | --- | --- | | --sandbox | -- | string | read-only, workspace-write, danger-full-access | read-only | --full forces danger-full-access | | --reasoning | -r | string | minimal, low, medium, high, xhigh | medium | Model reasoning effort | | --network | -n | boolean | true/false | false | --full forces true | | --add-dir | -d | string[] | repeatable paths | [] | Additional writable dirs |

Claude-specific

| Flag | Short | Type | Values | Default | Notes | | --- | --- | --- | --- | --- | --- | | --permission-mode | -p | string | default, acceptEdits, bypassPermissions, plan | bypassPermissions | --full also resolves to bypassPermissions | | --max-turns | -- | string | positive integer | effort-derived if unset | Parsed to number when valid | | --max-budget | -- | string | positive number (USD) | unset | Parsed to maxBudgetUsd | | --allowed-tools | -- | string | comma-separated tool list | unset | Split into string array |

OpenCode-specific

| Flag | Short | Type | Values | Default | Notes | | --- | --- | --- | --- | --- | --- | | --variant | -- | string | preset/model string | unset | Used if --model absent | | --agent | -- | string | agent name | unset | OpenCode agent selection |

Canonical enum values (from src/types.ts)

• Engine names: codex, claude, opencode
• Effort levels: low, medium, high, xhigh

For timeout/effort mapping, sandbox modes, and permission details, see references/engine-comparison.md.

---

Output Contract

All engines emit one JSON payload to stdout. Parse JSON, never text.

Success shape: { success: true, engine, response, timed_out, duration_ms, activity, metadata } Error shape: { success: false, engine, error, code, duration_ms, activity }

Error codes: INVALID_ARGS, MISSING_API_KEY, SDK_ERROR.

Heartbeat: every 15s on stderr ([heartbeat] 45s -- processing). stdout is reserved for final JSON.

For full JSON schema, field descriptions, and examples, see references/output-contract.md.

---

Skills

Use --skill <name> (repeatable). Resolves from <cwd>/.claude/skills/<name>/SKILL.md.

• Skill content prepended as <skill> XML blocks
• If <skillDir>/scripts exists, prepended to PATH
• For Codex, skill directories auto-appended to sandbox addDirs
• Path traversal names are rejected

---

Coordinator Mode

Use --coordinator <name> to load a coordinator spec from <cwd>/.claude/agents/<name>.md.

Coordinator file format: Markdown with optional YAML frontmatter.

• Frontmatter skills (array): auto-injected as repeated --skill
• Frontmatter model (string): default model unless CLI --model is set
• Frontmatter allowedTools (string or array): Claude-only, merged with CLI --allowed-tools
• Markdown body after frontmatter: coordinator system prompt content

Example coordinator file (<cwd>/.claude/agents/reviewer.md):

---
skills:
  - code-review
  - test-writer
model: claude-sonnet-4-20250514
allowedTools:
  - Bash
  - Read
  - Write
---
You are a senior code reviewer. Focus on correctness, edge cases, and test coverage.

Example invocations:

# Load coordinator persona
agent-mux --engine claude --cwd /repo --coordinator reviewer "Review recent changes"

# Coordinator + file prompt + inline prompt (all three compose in order)
agent-mux --engine codex --cwd /repo --coordinator reviewer --system-prompt-file prompts/repo.md --system-prompt "Prioritize auth paths" "Audit this module"

Prompt composition order:

1. Coordinator body (--coordinator)
2. File content (--system-prompt-file)
3. Inline text (--system-prompt)

Flag interactions:

• --model on CLI overrides frontmatter model
• Frontmatter skills merge with explicit --skill flags (coordinator skills first)
• For Claude, frontmatter allowedTools merge with --allowed-tools

Validation and errors:

• Coordinator path traversal is rejected
• Missing coordinator file returns INVALID_ARGS
• Malformed frontmatter returns INVALID_ARGS
• --system-prompt-file resolves relative to --cwd
• Missing prompt file or directory path returns INVALID_ARGS

GSD Coordinator Reference

agent-mux ships with a reference GSD (Get Shit Done) coordinator spec at references/get-shit-done-agent.md.

This is a multi-step task coordinator that orchestrates Codex and Claude workers for complex pipelines. It includes:

• Model selection heuristics (when to use Codex vs Claude vs Spark)
• Orchestration patterns (10x Pattern, Fan-Out, Research + Synthesize)
• Output contracts and context discipline rules
• Anti-patterns to avoid

To use the GSD coordinator:

# Copy to your project
cp references/get-shit-done-agent.md <project>/.claude/agents/get-shit-done-agent.md

# Invoke via agent-mux
agent-mux --engine claude --cwd <project> --coordinator get-shit-done-agent "Complex multi-step task"

# Or from Claude Code via Task subagent
Task(subagent_type="gsd-coordinator")

Customize the frontmatter skills list and output paths for your project. The spec is a template designed to be adapted.

---

MCP Clusters

Config search: ./mcp-clusters.yaml then ~/.config/agent-mux/mcp-clusters.yaml.

--mcp-cluster is repeatable. all merges all clusters. --browser is sugar for --mcp-cluster browser.

Bundled server: src/mcp-servers/agent-browser.mjs (browser automation).

See mcp-clusters.example.yaml for config format.

---

Bundled Resources Index

| Path | What | When to load | | --- | --- | --- | | references/output-contract.md | Full output schema, examples, field descriptions | Parsing agent output, debugging response shape | | references/prompting-guide.md | Engine-specific prompting tips, model variants, comparison | Crafting prompts for specific engines | | references/engine-comparison.md | Detailed engine table, timeouts, sandbox/permission modes | Choosing engine config, debugging options | | references/get-shit-done-agent.md | GSD coordinator spec (reference template) | Setting up multi-step task coordination | | references/installation-guide.md | Full installation walkthrough | First-time setup, prerequisites, troubleshooting | | src/agent.ts | CLI entrypoint and adapter dispatch | Trace invocation path | | src/core.ts | parseCliArgs, timeout, heartbeat, output assembly | Always for behavior truth | | src/types.ts | Canonical engine/effort/output types | Always for contract truth | | src/mcp-clusters.ts | MCP config discovery and merge logic | MCP cluster setup/debug | | src/engines/codex.ts | Codex adapter | Codex option/event behavior | | src/engines/claude.ts | Claude adapter | Claude permissions/turn behavior | | src/engines/opencode.ts | OpenCode adapter + model presets | OpenCode model routing | | src/mcp-servers/agent-browser.mjs | Bundled browser MCP wrapper | Browser automation integration | | setup.sh | Bootstrap script | First install or environment repair | | mcp-clusters.example.yaml | Starter MCP config | Creating cluster config | | CHANGELOG.md | Release history | Verify version-specific behavior | | tests/ | Test suite | Validate changes/regressions |

---

Anti-Patterns

• Do not use --sandbox danger-full-access unless explicitly authorized.
• Do not parse agent-mux output as text. Always parse JSON from stdout.
• Do not run parallel browser workers. One browser session at a time.
• Do not read agent output files with full Read; use tail -n 20 via Bash.
• Do not use --reasoning minimal with MCP tools (Codex rejects them).
• Do not send exploration tasks to Codex; use Claude for open-ended work.
• Do not use xhigh effort for routine tasks; high is the workhorse.

---

Staying Updated

This skill ships with an UPDATES.md changelog and UPDATE-GUIDE.md for your AI agent.

After installing, tell your agent: "Check UPDATES.md in the agent-mux skill for any new features or changes."

When updating, tell your agent: "Read UPDATE-GUIDE.md and apply the latest changes from UPDATES.md."

Follow UPDATE-GUIDE.md so customized local files are diffed before any overwrite.