MarshalFleet 0.2.0

Orchestration engine for driving a fleet of headless coding agents (Cursor, OpenCode, Codex, Antigravity, Claude Code) from one driver via MCP + Skills

Run a fleet of AI coding agents in parallel, in isolated git worktrees, and know exactly what each one cost.

Proof

One task, four routing strategies, measured cost and latency from the ledger — not a guess.

Strategy	Backend	Model	Status	Cost	Source	Duration	Tokens (in / out)
deepseek	opencode	opencode-go/deepseek-v4-flash	succeeded	$0.0029	native	81.8 s	11,740 / 1,977
claude	claude-code	claude-sonnet-4-6	succeeded	$0.3374	native	121.4 s	17 / 6,837
cmdcode	command-code	zai-org/GLM-5.2	succeeded	unavailable	unavailable	252.6 s	0 / 0
codex-glm	codex	z-ai/glm-5.1 (via EastRouter)	succeeded	unavailable	unavailable	283.0 s	231,075 / 7,812

cheapest: deepseek ($0.0029) · fastest: deepseek (81.8 s)

Each produced solution's tests: deepseek, claude, and cmdcode passed 6/6 — deepseek was cheapest, fastest, and correct, for ~1/115th of claude's cost. Full methodology and tables: examples/benchmark-output.md and docs/nerds.md.

Install

You need Python 3.11+, uv, git, and at least one backend CLI installed and logged in — Marshal drives agents, it does not ship one. marshal doctor tells you which are ready. (The Claude Code plugin launches the MCP server through uv, so it is required on that path too.)

Claude Code plugin — the fastest path. Brings the Skills and the MCP server in one step:

/plugin marketplace add chiruu12/marshal
/plugin install marshal@marshal

From GitHub, for the CLI and the Python library:

uv tool install "marshalfleet[mcp] @ git+https://github.com/chiruu12/marshal@v0.1.0"
# or
pipx install "marshalfleet[mcp] @ git+https://github.com/chiruu12/marshal@v0.1.0"

Drop @v0.1.0 to track main. The [mcp] extra is what makes marshal mcp work — without it the server exits before a host can connect.

Not on PyPI yet. uv tool install "MarshalFleet[mcp]" is the intended command once it is published; until then use the GitHub URL above, which installs the same package.

Backend CLI auth and MCP wiring: SETUP.md.

60 seconds

1. Configure a fleet. From your project repo, scaffold a starter fleet.config.yaml:

marshal init   # scaffolds fleet.config.yaml in the current repo

The scaffold ships every client commented out, so uncomment at least one and save. Using the codex example:

clients:
  codex:
    backend: codex
    model: gpt-5.5

2. Check the fleet is ready. doctor verifies auth, not just that a CLI is on $PATH — a backend you cannot actually run fails here rather than 3 seconds into a job.

$ marshal doctor
✓ repo: /path/to/your-repo (branch main)
✓ config: fleet.config.yaml (1 client)
✓ backend:codex: available
✓ plan:codex: logged-in

3. Dispatch a job. It returns immediately with a run id — the agent works in its own git worktree on its own branch. Your checkout is never touched.

$ marshal spawn --client codex --goal "Add a docstring to hello()"
hello-docstring.codex.d56489fe  codex/gpt-5.5  running  (poll: marshal status)

4. Watch the fleet. Any number of agents, any mix of providers, each with its own cost line.

$ marshal status
hello-docstring.codex.d56489fe  codex        exited_clean  unavailable  .marshal/worktrees/hello-docstring.codex.d56489fe

5. Review, then merge. From a driver agent over MCP: collect_run("<run_id>") returns the diff read-only, and integrate("<run_id>", message="...") merges it. exited_clean means the process exited cleanly — it does not mean the code is correct, so the diff review is not optional.

MCP tool reference: docs/mcp-tools.md. Orientation for drivers: call marshal_quickstart() first.

Why Marshal

• One base class, many backends — backend choice is a per-call parameter, never global.
• Parallel by default — each agent runs in its own git worktree until you explicitly integrate.
• Per-provider usage tracking — every run's cost is tagged by provenance; unknown cost is unavailable, never a fake $0.
• Robust headless execution — hard timeouts, process-group kill, and no prompting modes that deadlock without stdin.

How it compares

	Worktree isolation	Real parallelism	Per-provider cost accounting	Human merge review	Multi-repo
Marshal	yes — one worktree per run	yes — capped run_many	yes — native / admin-api / unavailable	yes — collect_run then integrate	yes — one MCP server, many workspaces
Hand-rolled git worktree scripts	yes — if you build it	possible — you manage threads/processes	no — unless you wire it yourself	possible — you own the merge step	no — one repo per script unless you extend it
Subagents inside a single coding harness	partial — often same checkout or sandbox	limited — shared process/context	partial — whatever the host exposes	varies — some hosts auto-apply	no — bound to one session/repo
Generic workflow orchestrators (CI, Airflow, Temporal)	no — not their job	yes — at the workflow layer	no — not agent-token aware	yes — human gates are the point	yes — but not coding-agent native

What you can drive it with

Seven backend adapters. Model is set per client in fleet.config.yaml (or ad-hoc via --model / MCP model=).

Backend	Model flag	Cost provenance
cursor	optional (defaults to CLI default)	unavailable — individual plans expose no per-run cost
opencode	opencode-go/* (required pattern)	native — tokens + cost from the CLI
codex	provider/model (e.g. gpt-5.5)	admin-api via EastRouter usage_api; else unavailable
claude-code	claude-* (e.g. claude-sonnet-4-6)	native — total_cost_usd + tokens
command-code	provider/model (e.g. zai-org/GLM-5.2)	unavailable — hosted account, no token/cost in stdout
goose	provider/model or bare model (e.g. cursor-agent/auto)	native when the provider reports positive cost; else unavailable (best-effort stream-json)
antigravity (experimental)	gemini-*, claude-*, etc.	unavailable — text-only output

Routing playbook: docs/model-playbook.md. Verification matrix: docs/status.md.

Architecture

Marshal is the infrastructure layer between a driver agent and a fleet of headless coding CLIs. The driver plans; Marshal creates worktrees, runs backends with timeouts, records usage to an immutable ledger, and returns diffs for review. A future end-user product (Chauffeur) will sit on top — see docs/chauffeur-future.md.

Full design: docs/design.md.

Documentation

• SETUP.md — clone-to-first-run setup.
• docs/usage.md — configure a fleet; drive it via MCP, CLI, or library.
• docs/mcp-tools.md — MCP tool reference.
• docs/config.md — every fleet.config.yaml key.
• docs/model-playbook.md — which client to route a task to.
• docs/status.md — what's built and verified.
• docs/design.md — architecture and backend cheat sheets.
• docs/nerds.md — numbers, methodology, and the stuff we argue about.
• docs/sources.md — primary sources.
• examples/ — runnable copy-paste examples (library_quickstart, pipelined then review, read_paths, adversarial teams, multi-workspace, per-client env:); see examples/README.md.

Contributing

• CONTRIBUTING.md — dev setup, quality gate, adding a backend.
• SECURITY.md — security model and private disclosure.
• CHANGELOG.md · CODE_OF_CONDUCT.md

License

MIT