minifleet

A small software factory you can run yourself. v0.8 beta

GitHub The skill What went wrong Other tools

Goal	How
Agents take work	One task board; agents claim tasks from it
Free first, paid when needed	Cheap models start; stuck tasks move up
Small tasks	Each task lists its files and a check
Resumable	Work is saved often; a retry continues from there
Logged	Every step of every task is recorded
Easy to debug	One command shows a task's full history
Nothing stuck	Alarms fire when work stops moving

minifleet is a short write-up of how to set that up. You don't install it. Your own coding agent reads it and builds a version that fits your repo.

Principles

Small tasks. Each task should take an agent about five minutes. A big job is just a lot of small tasks, each with its own check.
Resumable. Any task can stop at any moment and pick up later from its last save, on any machine.
Local first. Everything lives on your machines: a SQLite file, plain folders, and git. It keeps working with the internet off.
Cheap first. Free or cheap models take the work. A task moves to a better model only when it gets stuck.
Everything is written down. Every task keeps its prompt, progress and result, so you can always see what happened and why.
Pull requests are optional. Work lands on a local branch after a quick check. Open a PR when you're ready to share it, if you want one at all.
Tools before tokens. When the agents keep solving the same kind of problem, write a small script that solves it the same way every time, and save the tokens for work that needs thinking. The fleet looks back at its own history to find those repeats.
Self-improving. Every task, attempt and failure is a row in the SQLite file, so the fleet can ask itself questions: which tasks fail most, which models are worth their cost, where time goes. Every half hour it fixes one thing that answer points to.
Nothing gets stuck quietly. If work stops moving, an alarm says so.

What it's made of

Nothing fancy. It runs on your own machines and uses things you already have.

Piece	What it is
Board	One SQLite file that tracks every task and what happened to it
Inbox	A folder of task files you or an agent can drop work into
Agents	A small script per model, each working in its own git worktree
Logs	Plain files per task, plus an alerts file and a decisions file
Machines	Your laptop plus any spare computer, connected over SSH
Landing	Git branches: work lands on a staging branch, then on main once tests pass
Config	One JSON file listing your machines, models and limits

No server, no database to run, no cloud account. If you can read a folder and run sqlite3, you can see everything the fleet is doing.

The folders

~/fleet/
  board.db          the task board (SQLite)
  inbox/            new task files land here
  logs/<task>/      one folder per task: prompt, progress, output
  alerts.md         anything that needs attention
  decisions.md      questions for you, answered in place
  fleet.json        machines, models, limits, and where worktrees go

You choose where the agents' worktrees live. A shared spot like ~/fleet/lanes works well for warm lanes that stay ready between tasks. Or keep them next to each project, the way you would normally use git worktree. Just keep them out of Dropbox or iCloud, since a syncing folder and a busy build don't get along.

Warm lanes

My first version made a fresh git worktree for every task. Each one took about half a minute to set up and close to a gigabyte of disk, and they piled up all over the place. For five-minute tasks, that's a lot of waiting.

Now each machine keeps a small pool of worktrees that stay ready. When a task finishes, its worktree is reset to the latest code, but the installed packages and build caches stay put, so the next task starts in a few seconds. Disk use stays fixed.

A warm pool needs three safety rules, and I learned each one by losing work:

Never hand out a worktree that has a running process or a recently changed file, even if it looks abandoned.
Before resetting a worktree, save everything in it to a branch, including new files that aren't tracked yet.
Check what each finished task actually changed before it lands, so a stale worktree can't undo someone else's work.

A task's life

A task file lands in the inbox: what to do, which files it may touch, and a command that checks the result.
The board picks it up. The next free agent claims it, using the cheapest model that might do the job.
The agent works in its own worktree and saves its progress every few minutes. If it crashes, the next attempt starts from that save, with notes on what went wrong.
When the check passes, the work goes to a staging branch after a quick rebase and a short set of tests.
If something fails, the task goes back with the reason. After two stalls it moves to a stronger model.
Once an hour the full test suite runs, and staging is promoted to main.

More machines

Add a spare computer by listing it in fleet.json. The fleet reaches it over SSH, checks that it has git, node and your agent tools, clones the repo, sets up worktrees, and starts sending it tasks when it has room. Code moves between machines with plain git over SSH.

                                          _________
                                         /        /|   checks in every 30 min
                                        /________/ |   reads the numbers
                                        | watch  | |   fixes one thing
                                        | o o o  | |   writes it down
                                        |________|/

  _________        _________                _________     _________     _________
 /        /|      /        /|              /        /|   /        /|   /        /|
/________/ |     /________/ |             /________/ |  /________/ |  /________/ |
| inbox  | | --| inbox  | | --> | board  | |gt; | board  | | claim -->   |  lane  | |  |  lane  | |  |  lane  | |
| tasks  | |     | sqlite | |             |  free  | |  | cheap  | |  | strong | |
|________|/      |________|/  <-- result  |________|/   |________|/   |________|/
                                               |             |             |
                                               v             v             v
  ====================================================================================
    [##]--[##]--[##]--[##]  >>  check: rebase . quick tests . land
  ====================================================================================
                                                             |
                                            failed? back to the lane that made it
                                                             |
                                                             v
                                            staging ==> main   (hourly full tests)

What it looks like running

This is the live dashboard from my own fleet: every worker, what it's working on and for how long, how fast tasks are finishing and landing, and anything that needs attention.

Why it's built this way

Every rule came from something that broke. My favorite: a tiny bug let a few empty rows into the task list, every write after that failed silently, and the watchdog killed 169 tasks in eight minutes. Now only one program can write to the board, and it complains loudly when something goes wrong. The other 26 stories are here.

Getting better every day

A fleet that runs all night makes a lot of small mistakes. The useful part is that every one of them is written down, so the fleet can learn from them. Here's how that works:

A check-in every half hour. A capable model reads the numbers, picks the one thing most worth fixing, fixes it or hands it to an agent, and writes three lines about what it did. Small, steady improvements add up.
Questions it asks its own history. Because everything is in SQLite, it can ask: which kinds of task fail most? Which models are worth what they cost? Why do tasks get stuck? Where does the time go? The answers decide what to fix next.
Scripts instead of tokens. When agents keep solving the same kind of problem, the fleet notices and queues a task to write a small script that does it the same way every time. Model time is saved for work that needs judgment.
A list of what went wrong. Each real failure gets written up with its cause and a guard that prevents it next time. That list is 27 entries long, and it's the most useful thing in the project.
An ideas board. Agents can leave a note when they spot something that could be better. The half-hour check reads those notes too.

The first time I ran those questions, they found that 27% of attempts were being thrown away, mostly because tasks were handed out when there was no free worktree to run them in. That became the next fix.

Is it for you?

It's for one person, one repo, and a couple of machines. If you'd like a dashboard, a hosted service, or a team setup, one of the other tools will probably suit you better.

Try it

Open a coding agent in your repo and paste this:

Read minifleet.dev/skill and build me a minifleet for this repo.

It'll ask a few questions, then build it step by step.