Claude Code Open source agent harness, landing real features

A ledger your agents can't rewrite.

Iterum lets Claude Code agents work on your projects while you sleep. It keeps them from editing the same files or spending past your limit, records every step in a log they can't rewrite, and in the morning shows you what got done, what failed and what it cost.

Septa, the Iterum mascot: a nautilus holding a scroll
1SQLite file, agent.db, holds everything.
0servers to run. Sync uses a private git repo.
7harness layers checked by the doctor.
2triggers block every UPDATE and DELETE on the ledger.

Why you need it

Agents move fast. Your records should keep up.

"What did it actually do?"

A record you can check

Agents change state faster than you can review it, and a change nobody recorded only shows up when it breaks something. Iterum records every run step, queue task, file claim and merge as an event in an append-only ledger, where triggers reject edits and deletes. A drift check fails when knowledge is written without an event to explain it.

"It crashed at step 14."

Resume, don't restart

A long run fails partway through, and you either start over or guess where it stopped. Iterum writes each step down before it runs, so a resumed run skips the steps already committed and runs the rest.

"Two machines, two agents, one repo."

No stepping on each other

Parallel agents overwrite each other's work, and a stalled worker can wake up and write over newer changes. Iterum gives workers time-limited leases and refuses a stale worker's writes, and merges a branch only while its run still holds a claim on every file it changed.

The drift check exits 1, so a hook fails. Its rebuild also puts the claim back to nothing.

Who it's for: solo developers who want Claude Code agents working on their projects overnight.

How it works

Three contracts, kept apart

agent.db separates what's true now from what happened and from what you've concluded. Mix them and you can't tell which to trust.

runs · steps · tasks · claims

Control state

Mutable and local to one machine. Answers "what is true right now?"

events

Event ledger

Append-only. Every event gets a UUIDv7 and the name of the device that wrote it.

knowledge

Derived knowledge

A projection of the ledger. Wipe it and rebuild it from events at any time.

fleet/doctor.py

Harness doctor

Checks execution, tooling, context, lifecycle, observability, verification and governance, and writes its findings to harness-audit.json.

fleet/project.py

Drift check

Rebuilds knowledge and exits 1 on drift, so a hook can catch unrecorded writes.

fleet/sync.py

Cross-device sync

One command shares events between your machines through a private git repo.

fleet/run.py

Resumable runs

Every step is written down before it runs. Kill a run mid-step, resume it, and it skips the steps already committed.

fleet/queue.py

Work queue

Queue tonight’s plans with iterum add. A worker runs each on its own branch, commits what a failed one left there, and stops rather than start on uncommitted changes or on spend it could not count. Workers lease tasks with a fence, so a stale worker changes nothing; failed tasks wait in a dead-letter queue.

fleet/merge.py

Merge gate

A branch lands only while its run holds a live claim on every file it changed. With --check, it first runs a command, such as your build, on the merged result and refuses if it fails.

fleet/replay.py · eval.py

Regression suite

Replays a recorded run through the real run and queue code, with no model and no shell. Save a run as a case, and the suite fails when a change makes it end differently.

fleet/governor.py · telemetry.py

Spend ceiling

One ceiling for the whole fleet, summed from Claude Code's own telemetry. Once it is reached, runs stop before their next step and workers before their next task, and a stopped run can resume. A night can have its own limit too: iterum worker --max-usd counts only the runs that worker starts.

fleet/run.py · gate.py

Prompt steps

A plan step can be a Claude Code prompt. It runs only with --allow-claude and a dollar cap, gets only the Read, Edit and Write tools, and a hook refuses any edit to a file another run has claimed.

plugins/iterum · /iterum:fleet-plan

Plans from a sentence

A Claude Code plugin. Describe a feature in one sentence; it asks until nothing is open, writes the plan, a check and a plain-words plan document, proves the check fails today, and dry-runs the plan for free before asking to spend anything.

fleet/run.py --fix-retries

Fix loop

When the build or check fails after a prompt step, the error goes back into the prompt and the step runs again, a set number of times, each under its cap. The check reports every miss, so a retry sees them all.

fleet/sweep.py

Model sweep

Runs each plan several times in rotated order, each on its own branch, and reports pass rate beside cost. A run passes only if every step does, including the plan's own checks, so a check on the output can fail it.

fleet/approve.py

Approval gate

An irreversible action waits for a recorded human decision, bound to its exact parameters, and a restart does not ask again. A freeze stops workers claiming new tasks. Nothing calls the gate yet.

fleet/canary.py

Canary

Flags recent runs whose events, seconds or cost per run moved away from the day before. It catches change, not wrong output, and a fleet that got cheaper and faster overnight is worth a look.

Rebuild, don't trust

If it isn't in the ledger, it didn't happen

Knowledge is a projection. iterum project throws it away, rebuilds it from events and compares fingerprints. A mismatch means something wrote knowledge without recording why.

MATCHEverything is explained by the ledger. Exit 0.
DRIFTSomething changed off the record. Exit 1, so a hook fails.

Reports

Your fleet's day, on one page

One command turns the ledger into a page you can read over coffee: whether anything needs you, what ran, what it cost, and what landed. It opens offline, prints to PDF, and nothing leaves your machine.

DAYWhat needs a person, the day in numbers with 7-day trends, every run and its steps, spend by hour, merges.
WEEKSpend against your ceiling, runs and failures per day, cost per plan.
RUNOne run step by step, every event in order, the failure named.
❯ iterum report --open
A daily Iterum report: a banner saying 1 thing needs a person, tiles for runs, steps, merges and spend with 7-day trend lines, a table of runs with their cost, peak context and steps, and spend by hour by model

Example data. More in the guide.

A budget for the night

Know what tonight will cost before you sleep

Start the worker with the most tonight may spend. Each prompt step is capped on its own, a step starts only if its whole cap still fits, and the worker claims nothing once the night's spend reaches the limit. Your daytime Claude Code sessions do not count against it.

LIMITThe most tonight's runs may spend: --max-usd on the worker.
STOPNo claim and no step that would pass it. The rest stays queued.
MORNINGiterum report: each run's cost, apart from your own sessions'.

The cost is real: two features on the first real night, 2026-11-14, cost $0.0015. The terminal is illustrative, in the worker's real output format. A session can pass its own cap a little, Claude Code's estimate being client-side, so a night can too. More in the guide.

Sync across devices

One history, every machine, no server

Each machine keeps its own agent.db. Only events move, as plain text files in a private git repo you control.

01

Events travel, not the database

Copying a live SQLite file can corrupt it. Text files of events can't.

02

One file per machine

Each machine writes only its own events-<device>.jsonl, so git never has a conflict to resolve.

03

Merging is just adding

Events are never edited. Import skips ones it already has, so running it twice changes nothing.

04

Files only grow

Export never removes an event, so a rebuilt machine can't wipe its own history.

❯ iterum sync

Export, commit, pull, push, import and rebuild, in one go. The sync guide walks through setup.

Septa, a cartoon nautilus with one large eye, holding a rolled scroll

Meet Septa

Named for the walls that never come down

A nautilus grows by building a new chamber and sealing the old one with a wall called a septum. It never reopens a chamber. Iterum's ledger works the same way: every event gets a new chamber, and the old ones stay sealed.

Get started

Up and running in a minute

One script installs the iterum command and the Claude Code plugin, and records this machine's first audit. It asks for this machine's name, then prints the line to put in your shell profile. Built and tested on macOS; it does not run on Windows, and Linux or WSL may work but are untested.

macOSPython 3.14uvgitClaude Code
$ git clone https://github.com/shaynemeyer/iterum.git
$ cd iterum
$ ./install.sh                      # asks for this machine's name

Then follow the user guide, read the README, and the sync guide to add more machines.

↑ Top