fleetmux

Run a team, not a single assistant

Run AI teams the way you run containers.

fleetmux runs one supervisor agent and N worker agents as visible terminal sessions. The supervisor only judges and dispatches; workers only execute; a daemon — not the models — decides when the work is done. When a session nears its context limit it writes a handoff note and a fresh session takes its place, so one task can run for hours across many model sessions.

Get started GitHub

An animated terminal: the supervisor splits the goal and dispatches, two workers execute, the daemon checks each declared artifact, worker-1 writes a handoff note and becomes worker-1.1 in the same pane, then the task is COMPLETED.

The layout you actually get: supervisor top-left, history and daemon bottom-left, workers as tabs on the right.

Project manager

A project manager, not a secretary

Personal-assistant agents already spawn sub-agents, run scheduled jobs and fail over between models. fleetmux adds what a project manager does:

Lid closed, still running

Close the lid. Move. Open. It keeps going.

Shut the MacBook, carry it somewhere else, open it, get back online, and the run carries on. The daemon tells a machine that slept apart from a link that broke: when the gap is longer than two bridge renew periods it gives every session three periods to beat again before it judges the link lost. A startup that hits a network error is not blocked: it waits 30, 60, 120, then every 300 seconds and tries again. And nothing restarts while offline — before restarting any session the daemon checks the network, and with no network it only waits, spending no attempt and starting no new generation. The run does not pause, nobody has to resume it by hand, and it continues once the network answers.

01

Delivery accepted by the program

Whether the outputs exist, whether they contain what they must and whether the tests pass is decided by the daemon, not taken from the model's own report.

02

Sessions that continue without end

Near the context limit a session writes a handoff note and a fresh session takes its place; a frozen session restarts in place; daemon and supervisor watch each other.

03

Dispatch by a capability matrix

Before every dispatch the advisor picks the model and effort from a capability matrix (domain × task type × model, each cell with evidence), and the pick must pass a check against that matrix; a usage wall moves the slot to the next usable model on its role's chain, or pauses.

04

Visible throughout

Every agent is a visible terminal session you can watch and step into at any time.

05

Official CLIs, your own login

Each agent runs in its vendor's own CLI under your own login; no token is extracted, no client is impersonated and no API call goes through a proxy.

06

A budget per task

A budget card caps calls, rounds, hours and per-account quota; a usage-wall table drops a model tier or pauses the run so it can resume later.

07

Teams of teams

A worker can become the lead of its own sub-fleet, so one resident fleet can run several business lines, each started and stopped on its own clock.

How it works

How a task flows

The task carries its own definition of done: the artifacts it must produce, how long each must be and what each must contain.

Task goal + declared artifacts Supervisor splits and dispatches Workers execute one step each Daemon literal acceptance COMPLETED every artifact verified bounce — three bounces block the task
The supervisor can only declare files to check, never commands to run.
worker-1 context 60% worker-1.1 handoff note worker-1.2 same tab
A successor takes its predecessor's tab position; the retired screen and the note go to the history page.

Context rotation, not compaction

At 60% of the context window the session writes a three-section handoff note, the old screen goes to the history page, and a successor starts in the same place and reads the note. If the model does not write, a machine skeleton is used; a missing note alone does not block rotation.

A frozen session restarts in place; the daemon and the supervisor watch each other.

Mixed CLIs

Mix the CLIs you already run

Official Claude Code, official Codex CLI, Pi (Codex models and local models) and opencode mix in one fleet. The matrix below lists every supervisor × worker pairing the pair table knows, for task and service mode.

Supervisor × worker pairings, task mode. A pairing the pair table does not list is not supported.
Supervisor ↓ / worker → Claude Code Codex CLI Pi opencode dsh
Pi passed not supported passed smoke only passed
Codex CLI passed smoke only passed passed not supported
Claude Code passed not supported passed not supported not supported
Supervisor × worker pairings, service mode. A pairing the pair table does not list is not supported.
Supervisor ↓ / worker → Claude Code Codex CLI Pi opencode dsh
Pi passed not supported passed passed not supported
Codex CLI passed not supported passed smoke only not supported
Claude Code passed not supported passed not supported not supported
passed a real smoke run (1 supervisor + 2 workers, 4 checks) smoke mode only (starts with --lifecycle smoke) not supported (not in the pair table)

Codex workers (codex+codex) are still unverified; opencode is never a supervisor, and dsh is a worker-only backend in task mode. Pairs and their status (verified / unverified = --lifecycle smoke only / refused) live in fleetmux/config/fleet.yaml#cli_pairs; any pair the table does not list is refused with a reason before provisioning.

night pair: Pi supervisor + Pi workers 
fleetmux start --supervisor-cli pi --worker-cli pi \
  --supervisor-pi-model openai-codex/gpt-6-astra --supervisor-pi-thinking high \
  --pi-model flashnext/<local-model> --workers 2 --lifecycle <mode> \
  --allow-unsandboxed-pi --allow-development-v2

Use cases

What it is built for

Every start names a lifecycle; it decides what "done" means and how the run closes.

01

Operations that may only use local models

Some environments allow only models running on your own machines, and local models are poor at working together. fleetmux takes the collaboration out of the models and gives it to the daemon: the supervisor picks the next step, a worker carries it out, and the daemon decides when a turn ended, whether the result exists and whether a session hands over. --max-busy keeps concurrent prompts under the inference server's memory limit; the private Redis listens on a Unix socket only and opens no port.

02

Trading watch: strategies handed to AI, reviewed on a trigger

Your own program watches prices and indicators; when a level or a parameter is crossed it sends one request and the worker that owns that role runs a full review and answers in JSON. A request that names to skips the supervisor's turn, and the daemon checks the reply's fields before your program reads it. The fleet places no orders and knows no calendar.

03

Scheduled research report

Your own scheduler starts a fleet at fixed times of the business day: a supervisor plus two Claude Code workers that carry research skills and a web-search MCP. The goal declares the report file and the sections it must contain; the daemon accepts it literally, gives the run a hard time budget and closes the workspace when it ends.

04

Resident judgment service

Another program sends JSON requests; a request that names to goes straight to that role's worker. The daemon checks each reply against reply.required and reply.allowed, and the caller holds the fleet outside its working hours with pause and resume.

Quick start

Up and running in three steps

Open a cmux terminal, configure your Pi provider/model and replace local/my-model below.

  1. Check the requirements

    • macOS with cmux ≥ 0.64.25 (new-surface --command); run start inside a cmux terminal.
    • For Codex agents: Codex CLI ≥ 0.156.
    • redis-server on PATH (brew install redis); each run starts its own private instance and never touches localhost:6379.
    • Python 3.14 and the packages in requirements.txt.

  2. Install

    install 
    git clone https://github.com/justindbca/fleetmux && cd fleetmux
pip install -e .

  3. Start your first fleet

    first fleet 
    fleetmux start --workers 2 --supervisor-cli pi --worker-cli pi --lifecycle <mode> \
  --pi-model local/my-model --allow-unsandboxed-pi --allow-development-v2
echo '{"goal": "Survey the three most-cited papers on X and write a comparison",
       "hours": 4,
       "artifacts": [{"path": "worker-1/report.md", "min_chars": 800, "contains": ["Conclusion"]}]}' \
  | fleetmux task -                           # hand the goal to the supervisor
fleetmux status                               # task + per-agent state, context usage, inbox depth
fleetmux stop                                 # cancel; confirm runtime retirement before Redis shutdown

    New starts require Redis v2 and an explicit development opt-in; this is a development integration, not production acceptance.

    Known limitations

Read the full quick start →