This package has moved

MarshalFleet is now published as marshal-agents.

uv tool uninstall MarshalFleet
uv tool install "marshal-agents[mcp]"

Only the PyPI distribution name changed. The import package is still marshal_engine and the command is still marshal. MarshalFleet stops at 0.2.4 and receives no further releases; everything after 0.2.3 ships under the new name.

Run a fleet of AI coding agents in parallel, in isolated git worktrees, with per-run cost you can trust — measured where the provider reports it, marked unavailable where it does not, and never a fake $0.

Proof

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

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: Skills and the MCP server in one step.

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

From PyPI, for the CLI and the Python library:

uv tool install "MarshalFleet[mcp]"
# or
pipx install "MarshalFleet[mcp]"

The [mcp] extra is what makes marshal mcp work. Without it the server exits before a host can connect.

To track unreleased work on main:

uv tool install "marshalfleet[mcp] @ git+https://github.com/chiruu12/marshal"

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.6-luna

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.6-luna  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/myrepo-a1b2c3d4e5f6/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.

6. Record what you didn't merge. integrate records integrated for you. Nothing records the rest — so a run you reviewed and threw away looks identical to one nobody read.

marshal outcome <run_id> rejected --note "wrong approach"
marshal routing                  # which client's work actually got kept, per task kind

This is what turns the ledger into routing evidence. routing rates are computed over judged runs only, so skipping this step makes every client read 100% — flattering and useless. Tag work at spawn (--task-kind refactor) and the answer comes back per kind of task, with n_judged beside every rate and null rather than a guess when nothing has been judged.

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

Demo

A real run, start to finish: doctor verifies the fleet, spawn dispatches, status reports, and the diff lands in the agent's own worktree. The waiting is cut; nothing else is.

This one ran on OpenCode's free deepseek-v4-flash-free, which bills nothing and so reports no per-run cost — Marshal prints unavailable rather than inventing a number, while still recording the tokens. On a paid backend that reports cost, that column carries the real figure; see Proof. Recorded with VHS from assets/demo.tape.

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.
• Routing from evidence, not vibes. Record which runs you kept, and routing ranks clients by what actually survived review — per kind of task, with the sample size attached, and never ranked on a cost it could not measure.
• Robust headless execution: hard timeouts, process-group kill, and no prompting modes that deadlock without stdin.

How it compares

What you can drive it with

Model is set per client in fleet.config.yaml (or ad-hoc via --model / MCP model=). marshal backends lists what this build ships and marshal doctor says which are actually usable on your machine.

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