User guide

Running a fleet of Claude Code agents with Iterum

Iterum runs plans: numbered steps of shell commands and Claude Code prompts. It records every step in agent.db before running it, so a run can be killed and resumed, and it claims the files each step touches, so parallel agents cannot land over each other. This guide takes you from a first free run to shipping a feature written by a model, landed through a build check.

Free

Shell steps

Run any command. Nothing is billed. Every drill and dry run in this guide is free.

Billed

Prompt steps

Run claude -p on your account. Each is capped, and nothing runs without --allow-claude.

Rule of thumb

Plans from the app repo

Install iterum once. Run plans and landings from the repo they work on; everything else runs from any folder.

A typical session

  1. Plan it with /iterum:fleet-plan from a Claude Code session in the app repo: one sentence about the feature. It asks until nothing is open, then writes the plan, a check script and a plan document, proves the check fails on main, and dry-runs the plan for free. Planning a feature.

  2. Read the plan document: the files, the prompt, what the check looks for, the model and the cap. Nothing is billed until you say yes. To write plans yourself, see Writing plans by hand.

  3. Run it now, or queue it for the night. Now: start the receiver, load the telemetry settings, and run it with --allow-claude and --fix-retries 2 on a feature branch. Tonight: queue it with iterum add --plan, ask iterum budget suggest what the night may cost, and start a worker with that --max-usd. A night's queue.

  4. Land it with the printed command plus --check. If it is refused, fix on the branch and land again. Landing a branch.

  5. If anything stops, read its status and resume; nothing finished runs twice. When a run stops. Delete the merged branch when you are done.

Where to run what

Install iterum once (Before you start) and its commands run from any folder against one database, ~/.local/share/iterum/agent.db. Where you start still matters for two kinds of command: those that change your app run from the app repo, because steps run in the folder you start from and the merge gate lands the branch there; two harness commands need the Iterum repo.

Run fromCommandsWhy there
App repo, on a feature branchiterum run
iterum land
iterum sweep
Steps run in the current folder; the branch check and the landing use this repo.
Iterum repoiterum drill run
uv run scripts/seed-ledger.py
The built-in drill lists fleet/ and writes out/ in the current folder; the seed script is not part of the installed command.
Anywhereeverything else: iterum status, receiver, budget, recovery, view, add, worker, dlq, conflicts, approve, freeze, canary, sync, project, report, doctor, eval, scorecard, the other drillsThey work on the harness and its database, not on your app.
From the app repo
source <iterum>/.env.example             # telemetry, for prompt steps under a ceiling; once per terminal
iterum run feature.json

A feature session therefore uses two terminals: the telemetry receiver, and the plan and the landing in the app repo (Shipping a feature).

Chapter 01

Before you start

You need Python 3.14 (Iterum uses uuid.uuid7()) and uv. Prompt steps also need the claude CLI, signed in.

macOS. Iterum is built and tested on macOS. It does not run on Windows: it relies on Unix process groups and file locks. Linux, or WSL on Windows, may work but is untested.

Clone Iterum and run its install script:

git clone https://github.com/shaynemeyer/iterum.git && cd iterum
./install.sh

It asks for a name for this machine (every event records which machine wrote it; set ITERUM_DEVICE to skip the question), then installs the iterum command (editable, so a git pull updates it), audits the machine and records the audit as the first events in the ledger, builds knowledge, and installs the iterum Claude Code plugin, which adds /iterum:fleet-plan to every project. It stops at the first step that fails, and skips the plugin if claude is not installed.

At the end it prints the lines to add to your shell profile. Add them, then open a new terminal:

# ~/.zshrc or ~/.bashrc
export ITERUM_DEVICE=laptop            # the name you gave
export ITERUM_HOME=/path/to/iterum     # printed only if not cloned to ~/github/iterum
Why ITERUM_HOME? /iterum:fleet-plan looks for Iterum there and writes plans to $ITERUM_HOME/plans/, which git ignores, so your app's tree stays clean.
Shell cannot find iterum? Run uv tool update-shell and open a new terminal. Each iterum command runs a module as python -m would, so uv run python -m fleet.<module> from the Iterum repo still works. The database is created on first use at ~/.local/share/iterum/agent.db.
Chapter 02

Your first run: kill it, then resume it

iterum drill run runs a built-in six-step plan made of shell commands, from the Iterum repo. Step 5 sleeps for 20 seconds so you have time to kill it. Use a throwaway database while you learn:

  1. Start the drill against a scratch database.

    export ITERUM_DB=/tmp/scratch.db
    iterum drill run
  2. When step 5 starts, press Ctrl-C (or close the terminal). Steps 1 to 4 are already committed; step 5 is left proposed, with no outcome.

  3. Resume it with the run id it printed. Resume waits until the run's heartbeat is 60 seconds old, so a live run is never resumed by mistake. Add --force only if you know the old process is gone.

    iterum resume <run_id>

    It skips steps 1 to 4, reruns step 5, and finishes with run <run_id> done.

First run --resume 1 committed 2 committed 3 committed 4 committed 5 proposed 6 Ctrl-C heartbeat older than 60 s 1 skipped 2 skipped 3 skipped 4 skipped 5 committed 6 committed Resume skips every step in the committed set, read from the ledger, and runs the rest in order.
What you just did. Each step is written proposed before its command runs and committed after, so a kill always leaves an exact record of where it stopped.
Chapter 03

Planning a feature

A plan is a short list of numbered steps: usually a Claude Code prompt that makes the change, the build, a check that the change is there, and a commit. You do not have to write one: /iterum:fleet-plan writes it from one sentence and proves it before anything is billed.

Planning with /iterum:fleet-plan

Start Claude Code in the app repo and describe the feature in one sentence. The skill reads the repo and what past runs cost, then asks questions until nothing about the feature is open: what it does, which files, what counts as done, the model, the cap. A vague request gets questions, never a plan. Then it writes four files to $ITERUM_HOME/plans/<slug>/, proves the check fails on main, dry-runs the plan on a scratch database, and asks "Implement this feature?" Nothing is billed before your yes.

# in a Claude Code session started in the app repo
/iterum:fleet-plan add links back to the home page and to /notes on the not-found page
FileWhat it holds
plan.mdThe plan in plain words: feature, files, prompt, build, what the check looks for, model, cap, retries, chunks, and a last line Open questions: None.
plan.jsonPrompt step, build, check, commit; every step claims the same files.
dry.jsonThe same plan with the prompt replaced by echo dry, for the free run.
check.shRuns after the build. Prints every miss, one line each, on stderr, and exits 1 if there was any. Each line names exactly what is expected, because it becomes the model's feedback on a retry.
One task per file per night. A feature larger than one prompt step is split into chunks of one to three files. Chunks that share a file, or depend on each other, go into one plan as steps in order; only chunks with no file in common become separate plans. A run keeps its claims until it is landed, so a second plan on the same file would be refused.
Prefer to write plans yourself? Writing plans by hand covers the plan format, the rules every plan follows, prompt steps, check scripts and the free proofs, step by step.
Chapter 04

Prompt steps: letting Claude write the change

A prompt step runs one Claude Code session, billed to you, only with --allow-claude and a dollar cap. /iterum:fleet-plan writes the prompt; this is what the session it starts may do.

It can

Read, Edit and Write

Only those three tools, only inside the working directory (--restricted). Edits need no approval.

It cannot

Run commands

No shell, no MCP servers, no web. Put the build and your checks in shell steps after it.

It does not see

Your project instructions

No CLAUDE.md or AGENTS.md, and no git status. Put everything it needs in the prompt.

It is stopped by

Claims

The gate hook refuses an edit to a file another run has claimed, and tells the model why.

A prompt step that did not commit needs --force to resume. It may already have edited files, and running it again is a second billed session. Check git status and git diff on the branch first.
Chapter 05

Running and landing it

Once the plan is written and proven, the rest is: start the receiver, run it, land it. The first three stages below are free, and /iterum:fleet-plan has already done the first two.

FREE BILLED, CAPPED 1 Check a script that fails on main 2 Dry run prompt as "echo dry", scratch ITERUM_DB; fails at the check 3 Receiver start telemetry, source .env.example 4 Paid run --allow-claude 0.05 prompt, build, check, commit 5 Land iterum land with --check 6 Record cost, turns, what it showed check fails on the paid run: fix the check or the plan, resume (no new model call)
Free stages first. A check that already passes on main proves nothing, and a dry run that fails anywhere but the check means the plan is wrong. Both cost nothing to find out.
The paid run and the landing, from the app's repo
# terminal 1, anywhere: the receiver, on the same database the run uses
iterum receiver

# terminal 2, from the app repo, on a feature branch
source <iterum>/.env.example
git switch -c feat/note-footer main
iterum run <iterum>/plans/note-footer/plan.json --allow-claude 0.05 --fix-retries 2
run 663ba8f2873c started
  step 1  notes footer  -> committed
  step 2  build  -> committed
  step 3  check the footer  -> failed; fix retry 1/2 from step 1
  step 1  notes footer  -> committed
  step 2  build  -> committed
  step 3  check the footer  -> failed; fix retry 2/2 from step 1
  step 1  notes footer  -> committed
  step 2  build  -> committed
  step 3  check the footer  -> committed
  step 4  commit it  -> committed
run 663ba8f2873c done
land with: iterum land feat/note-footer --run-id 663ba8f2873c --fence 'file:app/notes/[slug]/page.tsx=16'

iterum land feat/note-footer --run-id 663ba8f2873c \
  --check "bun install --frozen-lockfile && bun run build"   # add --check yourself: it runs in a fresh copy, so install first

The fix loop

With --fix-retries N, a step that fails after a prompt step does not end the run. Its error, the last 2,000 characters, is added to the prompt, and the prompt step runs again, then every step after it, up to N times, each under its own cap. In the run above, the check named a missing sentence; the retry added it, and the check then named a missing link; the second retry added that and passed. Out of retries, the run fails as before.

What it costs. Across 54 Haiku prompt steps so far, the median cost was $0.0011 and 43 cost under $0.003; the most was $0.023, in 2 to 13 turns. The run above cost $0.00277 for three tries. The cap is Claude Code's own estimate, which spend can pass, so a step's real limit is close to its cap, not exact.
Chapter 06

Landing a branch

A finished run prints its land with: command, with one --fence per claimed file. Paste it as printed: fences with shell characters, like [slug], are already quoted. Add --check to build the merged tree before it lands.

iterum land builds the merge without touching your working tree, runs the check in a temporary worktree, then, in one transaction, requires a live claim at the given fence for every changed file and moves the target branch only if it has not moved since. Landing releases the claims.

It saysWhat happenedWhat to do
landed <branch> on mainMerged; claims released.Delete the branch when you like (git branch -d).
merge.refused, check failedThe merged tree failed your check, often two branches that each built alone. main is unchanged; the claims are kept.Fix it on the branch, commit, and run the same land command again while the claims are live.
a fence refused as stale, or a claim released or expiredToo much time passed, or another run took the file.Rerun the plan's edits on a new run, which claims again.
EmptyThe branch would not change any file on the target.Nothing to land.
Do not have the target branch checked out anywhere when you land. update-ref moves the branch, and a checkout of it would be left with a stale index.
Chapter 07

When a run stops

Every iterum run start lists runs that look dead and counts failed ones. iterum recovery gives the full list and halts any run whose same step has been tried too often. Find the run's status, then follow its path:

running heartbeat every 10 s done failed budget_exhausted halted killed: heartbeat stale nothing to do; resume refuses it fix the failed step's command, --resume <id> --plan p.json iterum budget set <usd>, then --resume <id> --plan p.json a person looks first, then --resume <id> --force wait until it is 60 s old, then --resume <id> --plan p.json
Every stop names its way back. A run is halted by iterum recovery when one step has been proposed --max-attempts times (default 3), so a person decides before it runs again.
iterum status                                 # exit 1 when a run is stale or failed
iterum recovery                               # list dead runs; halt over-retried ones
iterum recovery --idle-seconds 120 --max-attempts 5
iterum recovery halt <run_id> "superseded"     # give up on one; it leaves iterum status
iterum view trace <run_id>                    # the run stage by stage, failing stage named

Resume also refuses when it would be unsafe: a step's process is still alive, the plan's intents differ from the recorded ones, or a non-failed step's command changed. Each refusal prints the exact command to run once you have checked.

Chapter 08

Controlling spend

Set a ceiling for the whole fleet. Spend is counted from what Claude Code itself reports, so the telemetry receiver must be running.

iterum budget set 3        # a $3.00 ceiling; spend counts from the first time you set one
iterum budget              # show it
ceiling 3.00  spent 2.3859  headroom 0.6141 USD  (since 2026-11-11 10:44)
iterum budget reset        # count from zero again, keeping the ceiling
reset: 2.3859 USD no longer counted
ceiling 3.00  spent 0.0000  headroom 3.0000 USD  (since 2026-11-14 07:30)

A budget for the night. Give the worker its own limit with --max-usd. It counts only the spend of the runs that worker starts, so your interactive sessions do not eat into it, and the fleet ceiling still applies beside it. The worker stops before a claim, and a run before a step, that would pass it: a prompt step starts only if its whole cap fits in what is left. What did not run stays queued; a run stopped mid-plan is dead-lettered and can be resumed. A session can pass its own cap a little (Claude Code's estimate is client-side), so a night can too. Setting a ceiling changes only the limit; to count the fleet's spend from zero, iterum budget reset, logged as a budget.reset event with the spend it set aside.

What to set it to. Queue the night's plans with iterum add --plan, then run iterum budget suggest. For each task it prints the most it can be billed, (prompt steps + fix retries) × cap, and its typical cost, the median of past prompt steps on the same model; then the worker line with --max-usd at the sum of the worst cases. It changes nothing. A task queued as a plain command shows "cost unknown".

iterum budget suggest                              # each task's worst and typical cost, and the line below
iterum worker night-1 --until-empty --max-usd 0.30
Your own sessions count too. The receiver records any Claude Code session started from a shell where .env.example was sourced, and the ceiling adds up everything it records. Source it only in the terminal that runs plans and workers, and start your interactive claude elsewhere.
next step before it is proposed headroom covers it? shell step: more than $0 prompt step: its whole cap yes: run the step no: budget_exhausted committed steps stay; resumable
Checked before every step. Workers check before every claim and exit 1 at or below zero, leaving queued tasks queued.

Turning on telemetry

A plan with prompt steps under a ceiling refuses to start unless telemetry is on and the receiver answers with the run's own database. Start the receiver, then load the settings in the shell that runs the plan:

iterum receiver                              # listens on 127.0.0.1:4318
curl -s localhost:4318/v1/logs               # answers {"db": "/abs/path/agent.db"}
source <iterum>/.env.example                 # CLAUDE_CODE_ENABLE_TELEMETRY=1 and the endpoint
iterum status                                # RECEIVER: up, writing to this database
The ceiling is soft. A run can pass it by up to one step's spend, and runs that check at the same moment each can. Spend the receiver never received (because it was down) is not counted.
Chapter 09

Running work in parallel

Give each run its own working tree and branch, and point every run at the same database and receiver. Claims keep them from editing the same file; the merge gate keeps them from landing over each other.

Run A app/ · feat/note-tags Run B worktree · feat/latest agent.db claims · ledger · spend iterum receiver one receiver for both main land A, then B, each --check claims claims spend iterum land
One database, separate trees. If Run B's plan claims a file Run A holds, B is refused before any step runs, with A's run id in the message.
git worktree add -b feat/latest ../app-latest main
cd ../app-latest && bun install --frozen-lockfile        # each tree needs its own dependencies
# then start each run from its own tree, at the same time
git worktree remove ../app-latest                           # when done; refuses if it has changes
Starting runs together on a brand-new database? Run any iterum command, such as iterum budget, once first. Current code waits out the startup race, and initializing first avoids it altogether.
Chapter 10

The work queue

The queue holds work for later: shell commands, usually whole plans. iterum add queues one; workers claim them under a 30-second lease with a fence, run them, and report one outcome. A task gets one attempt unless you say otherwise, because a plan already retries inside itself (--fix-retries) and rerunning it whole cannot help.

iterum add "echo hello"
task 1 queued
iterum add "make test" --max-attempts 3      # retried after a backoff: 5 s, then 10 s
iterum worker worker-1 --budget-s 5

A task that must wait for another needs depends_on, which only Python has today (from the Iterum repo):

uv run python -c "from fleet import db, queue; db.init();
a = queue.add('shell', {'cmd': 'echo hello'})
b = queue.add('shell', {'cmd': 'echo world'}, depends_on=a)
print(a, b)"
iterum worker worker-1 --budget-s 5
worker-1  task 1 (shell)  done
worker-1  task 2 (shell)  done
uv run python -c "from fleet import queue; print(queue.results([1, 2]))"
['hello', 'world']
ready in_progresslease + fence done dead_letter haltedits dependents claim finish fail: retry after backoff max_attempts reached iterum dlq redrive <task_id> restores it and its dependents
One outcome per claim. A worker that stalls past its lease is fenced out: its late report changes nothing, and the task is reclaimed. Workers reap expired leases themselves; there is no separate reaper.
iterum dlq                                  # dead-lettered tasks
iterum dlq redrive <task_id>                # put one back, with what waits on it
iterum conflicts                            # tasks waiting for a person
iterum conflicts resolve <task_id> "keep the newer schema"
FLEET_WORK_MODULE=mypackage.mywork iterum worker worker-1   # your own do_work(task), from its project folder

Freezing the queue. When output looks wrong, stop new work before you investigate. A frozen queue hands out no tasks; workers finish the ones they hold. The freeze is per machine, and it does not stop iterum run.

iterum freeze "output looks wrong since 03:00"   # recorded as by ITERUM_DEVICE
iterum status                                    # FROZEN or not, and pending approvals
iterum thaw                                      # last, after the fix is queued
Approvals. iterum status lists approval requests and iterum approve|deny <fingerprint> settles one. Requests come from approve.require(), which nothing in Iterum calls yet, so the list stays empty until your own code calls it.

A night's queue

Plan each feature with /iterum:fleet-plan and answer no to "Implement this feature?". Queue each plan with iterum add --plan, the app repo and a branch name; iterum budget suggest gives the night's budget, and one worker runs them under it, --max-usd. For each task, the worker makes the branch from --base (default main), runs the plan there, and returns to the base detached, so iterum land can move it in the morning.

# terminal 1
iterum receiver

# terminal 2, the only one with the telemetry settings
source <iterum>/.env.example
iterum add --plan <iterum>/plans/not-found-links/plan.json --allow-claude 0.05 --fix-retries 2 \
  --repo ~/code/my-app --branch night/not-found-links
iterum add --plan <iterum>/plans/robots-sitemap/plan.json --allow-claude 0.05 --fix-retries 2 \
  --repo ~/code/my-app --branch night/robots-sitemap
iterum budget suggest      # one prompt step each: at most (1 + 2) × 0.05 = 0.15 per task
iterum worker night-1 --until-empty --max-usd 0.30
WhenThe worker
The plan finishesReturns the app to the base, detached: iterum land refuses a target that is checked out. The branch holds the plan's commit, ready to land.
The plan failsCommits whatever the failed run left on the task's own branch ("iterum: what task N left behind"), returns to the base detached, deletes the branch if it holds no commits (so the task can be queued again on the same name), and dead-letters the task with the end of the error: usually the check's own message.
The app has uncommitted changes before a taskHands the task back and stops, listing the changes. Every queued task stays queued. Nothing is cleaned up for you: the changes may be someone's work.
The ceiling, or the night's --max-usd, is reachedStops before its next claim, leaving queued tasks queued. A plan already running stops before a step it cannot afford; its task is dead-lettered and its run can be resumed.
A ceiling or --max-usd is set, but its shell has no telemetry settings or the receiver is not answeringStops before its first claim, or within 5 seconds once the receiver stops answering, leaving queued tasks queued: the ceiling could not count the night's spend. Start it from the shell where .env.example is sourced. It stops even for tasks with no prompt steps, since a task holds only a shell command.
Its time budget ends (--budget-s; with --until-empty alone there is none)Lets a running task finish, claims no more, and prints how many tasks it left queued.

Each run records its task (queue_task in its run.started event), so a run and the task that started it can be matched in the ledger. In the morning, iterum status, iterum dlq and iterum report show what finished and what failed; land each finished branch with iterum land and --check. Landing stays a decision for a person.

Use night/<slug>, not feat/<slug>. /iterum:fleet-plan's dry run already made feat/<slug>, and the worker cannot make a branch that exists. The empty feat/<slug> branches can be deleted.

Notifications. Set ITERUM_NOTIFY to a shell command and each worker runs it once when it stops, after writing the report, with a short summary on stdin: runs by status, how many are ready to land and need a person, today's spend, and the report's path. Unset, nothing is sent. A command that fails, or is still running after 30 seconds (it is killed, with anything it started), prints one line and changes nothing else. On macOS, a desktop notification:

export ITERUM_NOTIFY='osascript -e "on run argv" -e "display notification (item 1 of argv) with title \"Iterum\"" -e "end run" "$(cat)"'
It shows as from Script Editor; display notification cannot change the sender. If nothing appears, allow notifications for Script Editor in System Settings. Slack, email and Linux examples, untested, are in the setup guide.
Chapter 11

Seeing what happened

Every view is read-only except iterum canary, which logs a canary.fired event when it fires. The live-session half needs the claude CLI; without it you still get everything from the ledger.

CommandShows
iterum statusOne screen: freeze, spend, receiver, runs, queue, what needs a person, canary; exit 1 when something needs a person
iterum viewLive Claude Code sessions, then runs per agent from the ledger
iterum view trace <run_id>One run, stage by stage, with the failing stage named
iterum view stages [days]Failures per stage, default the last 7 days
iterum view context [session]Context size per session, or per request in one session
iterum budgetCeiling, spend and headroom
iterum budget suggestEach queued task's worst and typical cost, and a --max-usd for the night
iterum recoveryFailed runs and running runs whose heartbeat went stale
iterum canaryRecent runs that look unlike the day before
sqlite3 ~/.local/share/iterum/agent.db "select kind, payload from events where run_id='<id>'"The raw ledger for one run, including claude.finished (cost, turns, denials)
What the canary compares. Median events, seconds and cost per run for finished iterum run runs in the last hour, against the 24 hours before; it fires past a 50% change (--tolerance). It needs 5 earlier runs, and cost needs iterum receiver. It flags change, not wrong output: a fleet that got cheaper and faster overnight is worth a look.
Chapter 12

Reports

iterum report writes a self-contained HTML page into reports/ beside the database (~/.local/share/iterum/reports/) and prints its path. A page opens offline: no network requests, one small inline script for sorting tables and chart tooltips, and it reads the same with scripts off. It starts with a banner saying whether anything needs a person.

iterum report --open                    # today, with 7-day trends
iterum report --date 2026-11-12 --pdf   # another day, and a PDF of it
iterum report --days 7                  # the last 7 days
iterum report --run <run_id>            # one run, step by step
iterum report --json                    # the same data, for scripts
iterum report --serve                   # live, on 127.0.0.1:8780

A day or several-day report also writes a page for each run it lists and rebuilds index.html, so run ids are links and every page links back to the index. A day with no activity writes nothing and says which dates have data. --serve answers only on 127.0.0.1, refuses requests for any other host name, and stops with Ctrl-C.

A daily report: a banner saying 1 thing needs a person, the refused merge listed, four tiles with 7-day trend lines, the runs table with each run's cost, peak context and steps, one run failed at its second step, and spend by hour split by model
A day. The banner says whether anything needs you; here a run failed at its second step and a merge was refused by its check. Tiles carry the last seven days as a trend. Example data.
A seven-day report: a banner with runs, unfinished runs and spend, spend per day stacked by model, and spend since the ceiling was set as a line under a dashed ceiling
Seven days. Spend per day by model, then the running total since the ceiling was set against the ceiling itself. Further down: runs per day, failures by stage, cost per plan. Example data.
PageCommandShows
A dayiterum report [--date D]What needs a person; runs, steps, merges and spend with 7-day trends; every run with its steps, cost and peak context per request, marked when over the 100K a chunk should stay under; earlier runs touched that day; spend by hour; merges landed
Several daysiterum report --days NSpend per day and against the ceiling; runs per day by status; failures by stage with counts; cost per plan, one dot per run; the largest context peaks
One runiterum report --run <id>Status and first failing stage; a timeline of its steps; every event in order, failures marked with their details; its merges
Chapter 13

Syncing devices

Only the event ledger moves between machines. Each device writes its own events-<device>.jsonl in a sync folder that sits in a private git repo with a remote, and imports every device's file, skipping events it already has. Runs, steps, claims and the queue stay on the machine that owns them.

export ITERUM_SYNC_DIR=~/private-data/iterum      # the default; must be inside a git repo with a remote
iterum sync           # export, commit, pull, push, import, rebuild knowledge
iterum sync export    # only write this device's events
iterum sync import    # only merge every device's events
Keep files from retired devices. They are the only shared copy of those events. Importing the same file twice changes nothing.
Chapter 14

Testing changes to Iterum

There is no unit test suite. Changes are checked with drills that crash the harness on purpose, and with recorded runs replayed through the real code. Run them against a scratch database.

CommandChecksTimeCost
iterum drill mergeMerge gate refusals, the lock, a crash mid-mergesecondsfree
iterum drill claimsClaim refusal, resume, renewal, takeover of a paused agentabout 50 sfree
iterum drill killSIGKILL a worker mid-task and check recoveryabout 50 sfree
iterum drill run (from the Iterum repo)The six-step write-ahead drillabout 25 sfree
iterum evalReplays every stored case; exit 1 if a regression case failssecondsfree
iterum scorecard <before> [<after>]Eval cases at two git revisions; FIXED or BROKE per casesecondsfree
iterum sweep a.json b.json --repeats 5Plans run N times in rotated order; pass rate beside costminutes
export ITERUM_DB=/tmp/scratch.db ITERUM_DEVICE=test
iterum drill merge
iterum drill claims & iterum drill kill & wait
iterum eval add resume-case <run_id>    # keep a real run as a regression case
iterum scorecard main                   # did my working tree break any case?
When you add a check to a drill, break the code once to watch it fail, then undo the break by reversing your edit, not with git checkout, which also throws away uncommitted work.
Chapter 15

Settings

VariableDefaultEffect
ITERUM_DEVICEnone, requiredNames this machine on every event. Anything that writes an event fails without it.
ITERUM_DB~/.local/share/iterum/agent.db ($XDG_DATA_HOME/iterum/agent.db when that is set)The database, created on first use. If you set it, use an absolute path, so runs, the receiver and the merge gate started from different folders share it.
ITERUM_CLAIM_TTL300Seconds a run's claim lasts between renewals.
ITERUM_IDLE_SECONDS60Heartbeat age after which a running run counts as dead, for recovery and resume.
ITERUM_MAX_ATTEMPTS3Default --max-attempts for iterum recovery.
ITERUM_SYNC_DIR~/private-data/iterumThe sync folder, inside a git repo with a remote.
ITERUM_NOTIFYunsetA shell command each worker runs when it stops, with a summary on stdin (Notifications).
FLEET_WORK_MODULEthe shell runnerA module exporting do_work(task) for iterum worker, found from the folder you start it in.
FLEET_TASK_TIMEOUT_S600Seconds one task's command, usually a whole iterum run, may run; then it is killed and the task fails.
FLEET_WORKER_BUDGET_S12The worker's --budget-s when neither it nor --until-empty is given.
.env.examplenot loadedsource it to send Claude Code telemetry to iterum receiver; required for prompt steps under a ceiling.
Chapter 16

Troubleshooting

You seeWhyFix
ITERUM_DEVICE is not set. Name this device firstNo device name in this shell.export ITERUM_DEVICE=laptop
command not found: iterumNot installed, or uv's tool folder is not on your PATH.uv tool install --editable <iterum>, then uv tool update-shell and a new terminal.
No module named 'fleet'Ran a module as a file, or python -m outside the Iterum repo.Use iterum <command>, or uv run python -m fleet.<module> from the Iterum repo.
a plan that declares files must not run on mainYou are on the target branch.git switch -c feat/<name>
this plan has prompt steps, which are billed to youNo cap given.Add --allow-claude 0.05 (the cap per prompt step).
prompt step 1 declares no filesA prompt step must list what it may edit.Add ["file:..."] as the step's fourth field.
a ceiling is set, but claude would not report its spendTelemetry settings not loaded in this shell (a worker prints it after "stopped: no task was claimed").source .env.example
the telemetry receiver ... did not answerReceiver not running.Start iterum receiver, with the same ITERUM_DB if you set one.
the telemetry receiver writes to X, but this process reads YTwo different databases.Unset ITERUM_DB in both shells, or make it the same absolute path.
file:app/page.tsx held by worker-1 (run 813631d110df)Another run holds the file.Wait for it to land or expire, or work on another file.
stopped before step 2: fleet headroom is -0.0100 USDOver the ceiling.iterum budget set <usd>, then resume with the same plan.
may still be alive: its heartbeat is 12s oldThe run might still be running.Wait, or --force if you know it is gone.
does not match this plan at step 3Different plan file than the one the run started with.Resume with the original plan.
is a prompt step that did not commitIt may have edited files; rerunning is billed again.Check git status and git diff, then resume with --allow-claude <usd> --force.
zsh: no matches found: --fence file:app/[slug]/...An unquoted fence typed by hand.Quote it: --fence 'file:app/[slug]/page.tsx=12'. Printed land commands are already quoted.
↑ Top