Repository navigation
Releases
v1.3.0 — the foreground queue
Delegations run headless, which is right for fan-out and wrong when you want to watch the work. This release inverts it: an orchestrator enqueues, and an attached session executes in its own conversation, where every prompt, tool call and result is visible.
fleet enqueue "Add a /health endpoint with a smoke test" --label healthIn the session that should do the work:
fleet queue attach --worker my-session --poll 300 # then /loop 5m to drainNo UI automation and no external controller — the session polls, claims and executes on its own.
What it guarantees
- Exactly one execution. Claims use
O_EXCL; six workers racing for four tasks take one each. Enqueuing identical work in a directory returns the existing task rather than adding a second (--keycontrols that identity). - One drainer per project. A second
attachis refused while the first is still polling, so a competing controller cannot start. - Recovery from a crash. A claim is a lease held by heartbeat, not by a process. If a session dies, nothing renews it and the task returns to
pendingwithin its TTL — 30 minutes by default,--leaseto change.--owner-pidgives immediate release when the caller has a genuinely long-lived process. - Completion notifications via Notification Center, delivered with the screen locked while the machine stays awake.
queue: done=1, pending=2
worker: my-session - holding the slot (last seen 2026-09-07T17:02:29+00:00, poll 300s)
The honest limit
Nothing external can inject a turn into a running session without UI automation. Each session does expose a private socket, but building a third-party client for an undocumented protocol would break on the next version bump — so this polls rather than being pushed, and pickup latency is bounded by the interval. Five minutes by default; lower --poll for a tighter loop.
Also in this release
Everything from v1.2.0's line of work is included: fleet adopt for picking up a prior Claude Code or Codex session (now finding sessions in deep directories, which a truncated-path bug had hidden), resume commands printed for every delegation so any worker's conversation can be opened, and plan-level context/decisions carried into every task so workers get the reasoning rather than only the conclusion.
104 tests, up from 77 in v1.1.0, passing on Python 3.9/3.11/3.13 with no backends installed and no credentials.
v1.1.0 — session handoff and the task workflow
Two features.
Pick up a project already in flight
Both CLIs keep transcripts on disk, so prior work in a directory can be continued instead of re-explained:
fleet adopt # CLI SESSION ID TURNS UPDATED TITLE
1 codex 01a06ade-18a3-7e71-a653-c79efc68b154 876 2026-09-07T05:29:19 Check project progress
4 claude a38e921b-29f9-4919-b1bf-de00cddb6f4d 605 2026-09-07T05:07:08 Self-distillation papers review
fleet adopt 01a06ade --as work # same CLI — resumes it for real
fleet adopt a38e921b --as work --handoff terra # other CLI — carries the transcriptSame-CLI adoption registers the native session id, so --session NAME resumes the actual conversation. Cross-CLI cannot: a Claude session has no meaning inside Codex, so --handoff extracts the transcript, strips harness scaffolding, budgets it, and opens a fresh session on the target model seeded with it.
The orchestrator skill runs fleet adopt at startup and asks before assuming a project is new.
Two format details this depends on: payload.id is the Codex thread codex exec resume accepts (payload.session_id is the lineage root and repeats across resumes), and Claude's cwd→directory encoding is lossy, so matches are confirmed against the cwd recorded inside the file rather than decoded from the name.
A task workflow with gates that are checked, not asserted
fleet task start add-rate-limiting # cuts fleet/add-rate-limiting, refuses a dirty tree
fleet task receipt add-rate-limiting # attach the notebook receipt
fleet task review add-rate-limiting --verdict pass --by fable
# ... fill in .fleet/tasks/<slug>/understanding.md ...
fleet task status add-rate-limiting # exit 0 only when all four are green [x] branch on fleet/add-rate-limiting
[x] receipt receipt.ipynb (9 cells)
[x] review pass by fable
[ ] understanding 0 chars of prose
NOT ready to merge - open gates: understanding
Every run now writes a receipt.ipynb automatically — the goal, each delegation with its prompt, response, model, tier and duration, the branch and diffstat, and a verification cell to fill in. Plain nbformat 4.5 JSON, so it needs no notebook libraries and validates cleanly under the real nbformat.
A receipt can only be attached from a run that happened in this repository, and an untouched understanding template contributes nothing toward its gate. Both were defects found in review before release.
Also
fleet receiptwrites a receipt for any past run- Transcripts are read as UTF-8 explicitly rather than following the platform locale
- Turn counts mean the same thing on both backends (Claude files tool results under the
usertype; those are not turns)
77 tests, up from 54 in v1.0.1, passing on Python 3.9/3.11/3.13 with no backends installed and no credentials.
v1.0.1 — path containment fix
Security patch. Upgrade from v1.0.0.
Fixed
Path traversal via a plan's label — the field was interpolated into a directory path created with mkdir(parents=True) and never validated. A plan containing "label": "../../../../ESCAPED" created a directory outside FLEET_HOME and wrote plan.json into it. Containment now happens once in new_run_dir(), which also covers plan.json and run.json — those never used the per-write guard and were safe only because their filenames are constant.
Duplicate task ids collided on case-insensitive filesystems — Survey and survey passed validation as two distinct tasks, then wrote to the same artifact on macOS and Windows, silently losing one result. Ids are now compared case-insensitively.
run_task could raise instead of returning a result — validation raised past the helper that guarantees a uniform result shape, and fleet doctor --auth calls run_task unguarded. A bad id now returns a failed result and writes no artifact.
Malformed plans produced tracebacks — a non-object task gave AttributeError, a missing tasks key gave KeyError. Both now report a message naming the offending task.
Notes
54 tests, up from 44. The new ones pin run-directory containment for hostile labels; nothing covered that before, which is why the suite stayed green while the bug was live.
Path traversal here requires a plan file you already control, so the practical exposure is low for local use — but it matters if you generate plans from model output or accept them from elsewhere, which is a normal way to drive this tool.
v1.0.0 — agent-fleet
Superseded by v1.0.1. This release contains a path traversal via a plan file's
labelfield. Please upgrade.
One orchestrator, both CLIs, every model.
Run it inside Claude Code or inside Codex. Either way, the app you're in becomes the orchestrator: it plans the work, hands each piece to whichever model actually fits it — on either backend — reviews what comes back, and escalates when something fails.
Claude Code ──┐ ┌──► claude -p ──► opus · sonnet · haiku
├──► fleet ──────┤
Codex ──┘ └──► codex exec ──► sol · terra · luna · mini · spark
No daemon, no server, no SDK. A single dependency-free Python script that shells out to CLIs you already have.
Install
git clone https://github.com/hopit-ai/agent-fleet.git
cd agent-fleet
./install.shWhat's in it
- Graded routing.
(kind, complexity) → tier → model, a plain lookup with no LLM call. Renames and boilerplate go to a small fast model; concurrency bugs go to a big one. Defined inroster.json, so adding a model or reweighting the policy never touches code. - Cross-family review. Delegate work to one model family and have the other review it. Different families fail in different places, so a GPT model reviewing a Claude diff catches what a same-family review nods past.
- Parallel waves. Tasks with no unmet
depsrun at once in separate processes, each with its own context window. Upstream output is injected into dependent prompts automatically. - Named sessions. Persistent conversations for work that builds on itself —
--session builderresumes across separate CLI processes. A session pins its model, backend and cwd. The pattern worth using: abuildersession on one family and areviewersession on the other that has seen every prior round. - Sandboxed by default, scoped to the task's
cwd.readonly: truedrops to read-only and always beats--yolo, including on the session-resume path. - A ledger. Every run recorded under
~/.fleet/runs/with the plan, per-task JSON results, and raw output.
Requirements
Python 3.9+ (stdlib only) and at least one of Claude Code or the Codex CLI. Having both is the point, but it degrades gracefully to one — and fleet route --all works before you install either, so you can inspect the policy first.
Notes
Verified against Claude Code 2.1.263 and codex-cli 0.153.3. 38 tests, passing on Python 3.9/3.11/3.13 with no backends installed and no credentials.
The default roster reflects the models available today. Providers rename and retire models; if fleet doctor shows something unreachable, edit roster.json — that's what it's for. Nothing in the design depends on a particular model existing.
MIT licensed.