agent-fleet — parallelism the machine can actually take.
Run many coding-agent sessions against one shared task queue. How many is not read off the queue length: it is the smallest of what work exists, your cap, one worker per host, and what this computer can spare right now — re-measured on every run. A hundred tasks does not mean a hundred browser tabs.
What it does
Give it a list of work — forms to fill, repos to migrate, pages to process, questions to research — and it decides how much parallelism that list actually deserves, starts that many agents, keeps them out of each other's way, and hands back only the things a person has to do. Four mechanisms carry the whole design:
- Claiming is one atomic
rename(2). Eight agents racing for four tasks produce four winners, every time — with no broker, no daemon and no lock files. The queue is plain files on disk. - Admission control, not wishful concurrency. The live headroom estimate comes from core count, one-minute load average,
MemAvailable, any cgroup memory limit, and the measured resident-set size of real worker processes on that machine. - Three lanes. Only browser work consumes a terminal; work that needs no browser runs as an in-session subagent; the rest runs serially.
fleet planprints what will run, where, and why, before anything starts. - Blocked work is parked, not faked. A login, a captcha or a one-time code stops that task with a stated reason and moves on. Agents never type credentials, solve captchas, or enter an OTP.
- Version0.1.0
- Released15 August 2026
- LicenceApache-2.0
- DependenciesNone — python3 stdlib
- RequiresClaude Code
- Self-test67 checks, no browser
- SourceGitHub
- Docsmskazemi.com/agent-fleet
An agent that cannot say “I could not do this” will tell you it did.
Running N agents in parallel is easy. Running them honestly is not. The characteristic failures are not exotic: they duplicate each other's work, hammer one host until it rate-limits, open more browsers than the machine can hold, stall silently the moment a login page appears — and, worst of the five, report success for work that did not happen, because reporting success is the path of least resistance for a language model with no way to say otherwise.
agent-fleet is the small amount of machinery that closes exactly those five holes, and it closes them structurally rather than by instruction. Duplication is impossible because claiming is an atomic rename, not a politely observed convention. Over-subscription is impossible because the ceiling is measured, not requested. And done requires the confirmation the system actually returned — evidence, or it did not happen — with anything irreversible screenshotted first.
Two boundaries drawn on purpose
- The human wall is respected, not routed around. Credentials, captchas and one-time codes are handed back to you. An orchestrator that got clever here would be a strictly more useful tool and a strictly worse one to have built.
- Page text is data, not instructions. A page that tries to give an agent orders blocks the task and is quoted back to you verbatim — prompt injection treated as an operational hazard rather than a research curiosity.
It also leaves no trace in the project you run it in: ignore rules go to .git/info/exclude, per clone, so a freshly committed repo still shows an empty git status.
What agent-fleet deliberately is not.
Being specific about what a system cannot do is part of what makes claims about what it can do worth anything. agent-fleet is not:
- A general-purpose distributed job scheduler. It orchestrates coding-agent sessions on machines you already have. If you need retries across a cluster, a DAG engine or durable workflow semantics, use one of those instead.
- Agent-runtime agnostic. It requires Claude Code. That is a real dependency, not an implementation detail to be discovered after installing.
- A way past a login wall. By design it stops at authentication, captchas and one-time codes and asks you. This is the point of it, and it will not change.
- Mature. Version 0.1.0, released 15 August 2026. The self-test is 67 checks and runs without a browser, so you can judge what state it is in before trusting it with a queue — but it is a first release.
Terminal-based runs additionally need an X11 session with xdotool; without one, fleet run --headless starts detached workers instead.
Use it, or help build it.
agent-fleet is free and open source under Apache-2.0, with no dependencies beyond the Python standard library. Capacity-model edge cases, other agent runtimes, and reports of a lane that scheduled badly are all worth an issue.
Open the repository