Skip to content

Releases

v1.3.0 — the foreground queue

Choose a tag to compare

@ArchieIndian ArchieIndian released this 07 Sep 17:17

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 health

In the session that should do the work:

fleet queue attach --worker my-session --poll 300   # then /loop 5m to drain

No 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 (--key controls that identity).
  • One drainer per project. A second attach is 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 pending within its TTL — 30 minutes by default, --lease to change. --owner-pid gives 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

Choose a tag to compare

@ArchieIndian ArchieIndian released this 07 Sep 05:35
25aa6cc

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 transcript

Same-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 receipt writes 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 user type; 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

Choose a tag to compare

@ArchieIndian ArchieIndian released this 07 Sep 04:45

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

Choose a tag to compare

@ArchieIndian ArchieIndian released this 07 Sep 04:45

Superseded by v1.0.1. This release contains a path traversal via a plan file's label field. 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.sh

What'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 in roster.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 deps run 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 builder resumes across separate CLI processes. A session pins its model, backend and cwd. The pattern worth using: a builder session on one family and a reviewer session on the other that has seen every prior round.
  • Sandboxed by default, scoped to the task's cwd. readonly: true drops 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.