Costs and reports

Foreman keeps a record of every story session: what it cost, how long it took, how many rounds it needed, and the tokens each agent used. foreman report prints those records from the command line, foreman report --tokens breaks them down by agent with hints on where to save, and the dashboard shows the same numbers on its Insights tab and its Tokens panel. Costs are shown in dollars and time; this page says where each number comes from and what it means, and quotes none. Read it when you want to know what a story costs you, which agent uses the most, or why a run took longer this week.

foreman report

foreman report reads the run records in <state folder>/runs/ (Run records below) and prints the story sessions’ cost and time, per day and per result. Days are UTC, by when a session ended.

foreman report
foreman report --since 2026-10-01
foreman report --tokens
foreman report --json

--since YYYY-MM-DD counts only sessions that ended on or after that day; every section honours it. --json prints the same totals as one JSON object. --tokens prints the token report instead (next section), and --tokens --json prints the token view itself. Any other argument prints the usage line.

The plain report has these sections, in this order. A section with nothing to count is left out.

Section	What it shows
Per day (UTC)	One line per day: sessions, stories, how many shipped, the cost in dollars, the time, and the day’s average first-turn context (“first turn 21.1 k”), the size of what a session starts with.
By result	One line per result (shipped, blocked, failed, crashed and the rest): sessions, cost and time.
Total	Sessions, stories, shipped, cost, time, the average first-turn context, and how many sessions have no cost. A session that died before Claude reported its cost counts toward time but not cost.
Watchdog	Only when the watchdog stopped a session: the stories and sessions it stopped, how many at the hard limit (4 times the build limit), and the work done again, in tokens and agent time. A stopped session never reports its cost, so the redone work is measured in tokens and time.
Learning	Only when there is learning to count: the learner’s calls and spend, and the learned changes added, kept, rolled back, retired and undone (How Foreman learns).
Checks (per story)	Only when a story has full-suite check records in check-runs.jsonl, also when there are no sessions: per story, the real full-suite runs and their minutes, the quick runs and their minutes (only when there are some), the reuses of a record, the waits on a run in progress in another slot (only when there are some), the build rounds (when the story has run records), and the hand runs of a check the Bash guard denied (Story sessions).
Models (set and ran differ)	Only when an agent ran on another model family than its role is set to: a line per agent with the story, the day and the mismatch, such as “test (foreman:tester) is set to Haiku but ran on Opus 5.5” (Agents and traits).
Tokens	The token report, when there are token counts.

With no records the report says “No story sessions recorded yet.” (or “since <date>”) and still prints the Learning, Checks and Tokens sections it can. The --json object carries since, days, results and total, and watchdog, learning, checks and models only when they have something; each check entry has fullRuns, minutes, quickRuns, quickMinutes, reused, waited, denied and rounds.

The token report

foreman report --tokens prints what each agent role used, in tokens only: no cost and no money anywhere in it. The counts come from the agents rows of the run records and from the learner’s lines in learner.jsonl. Days are UTC, by when a session ended, as in the plain report, so the two line up day for day.

The roles are the architect, the builder, the tester, each reviewer by its name (“security reviewer”), “the story session itself” (the orchestration, the session’s own turns outside any agent), the learner, and “other” for an agent of no known role. The report has four parts:

1. A table, one row per role, biggest week first: today, the last 7 days, this run (everything since the run’s start, as state.json records it; zeros without a run) and a sparkline of the last 14 days, one bar per day scaled to the biggest. When a role’s sessions recorded the model it ran on, the models are shown in brackets after the role.
2. Last 7 days, one line per role: input, output, cache read and cache write, such as “1.2 M in · 85 k out · 9.8 M cache read · 410 k cache write”. Counts are shown as 850, 8.5 k, 85 k, 1.2 M and so on.
3. Per story (last 14 days), at most 20 stories, biggest first: a story’s sessions summed, then each agent’s total, with its models in brackets.
4. Hints, plain sentences on where to save, and then how many sessions of the last 14 days have no token counts (older records, or a session that never reached its final event).

The four hints and the thresholds that raise them:

Hint	When it appears
lowCache	A role’s input side over the last 7 days (input plus cache read plus cache write) is 1 M tokens or more, and less than 50% of it was read from the cache. Keeping the start of its prompt the same from call to call lets more of it be read from the cache.
growth	A role ran on at least 2 stories in each of the last two 7-day windows, and its tokens per story in the last 7 days are more than 1.5 times the week before. Look at what changed in its prompt, skills or the stories it gets.
fixRounds	Fix rounds took more than 50% of the builder’s tokens in the last 14 days, across at least 2 stories. Clearer plans, or running the checks before handing over, could save rounds.
quietReviewer	A reviewer ran on at least 5 stories in the last 14 days, raised no finding on any of them, and used at least 10% of all tokens. It may not be needed on every story.

foreman report --tokens --json prints the view as JSON: roles, stories, hints, unknown (the sessions without counts) and empty. With nothing recorded yet the plain form says “No token counts recorded yet.”

Insights

The dashboard’s Insights tab (#insights) draws the same records for the last 7 and 14 days, from the server’s /api/history. Its header says where the numbers come from: “The last 7 days, from N story runs since <date>. Days are UTC.” Until something has finished it says so, and the charts fill in as stories finish. See Dashboard for the tab itself.

Four tiles for the last 7 days:

• Stories shipped, with the average per day.
• Ship rate, the share of finished stories that shipped, with how many did not.
• Typical time to ship, the median wall-clock time of a shipped story, with the share that shipped on the first try (one round).
• Spend, the cost of the stories that finished, with the cost per shipped story.

Then four charts, each with its numbers as a table as well, and each column or bar focusable with its values:

• Velocity: stories finished each day, shipped and did not ship.
• Usage by agent: tokens each day by role, cache reads included.
• Spend per day: what the stories that finished each day cost.
• Where the time goes: the average minutes per stage for a shipped story in the last 7 days, as Design, Build, Test and Review.

The command centre also has a Tokens panel, beside Live feed, Up next, Finished and Progress, drawn from /api/tokens: the same role table (Role, Today, 7 days, This run, 14 days) with each role’s 7-day line and models, “Per story, last 14 days” with each agent’s total (hover for its in, out and cache counts), the Hints, and the sessions without counts. Until a story finishes it reads “Token counts per agent appear once a story finishes.” The panel formats no number itself and shows no money; the spend lives on Insights and in foreman report. Beside each running agent the command centre names its model, and adds a note when it ran on another model family than its role is set to.

Run records

A run record is one JSON file per story session, <state folder>/runs/<story>-<yyyymmdd-hhmmss>.json, written when the session ends. It is what every report above reads, so nothing here needs the session’s log to still exist. The switch features.costMetrics (“Run records” on the Settings tab, on by default) writes them; off, there is no record and no cost, though the run’s own counts still go up. The fields:

Field	What it holds
story, slot	The story’s id and the slot it ran in.
result	The session’s final result (shipped, ready-to-promote, blocked, failed, halted, deferred, held, empty), else why it died (rate-limit, outage, api-credit, credit), else crashed; stopped when you stopped it (skip, take over, restart), interrupted when the run was stopped.
costUsd, turns	From the session’s final event; null when it never got there.
firstTurnTokens	The context of the session’s first turn; null when unknown.
minutes	Wall-clock time from start to end.
rounds	The build rounds, counted by tester starts.
serious	The blocker and major findings written for this story during the session, the rounds sent back and fixed included.
learned	The learned items (L-n) the story’s agents were given, so a trial can be measured.
stages	The minutes each stage had an agent running: architect, build, test, review, with agents side by side counted once.
agents	One row per agent plus the session’s own orchestration: role, name, agent, model, input, output, cacheRead, cacheWrite, turns, round. Null when unknown.
startedAt, endedAt	ISO times.
cause	environment, only on a failed session the environment ended; learning leaves such a run out of every count.
modelMismatches	Only when an agent ran on another model family than its role is set to: role, name, agent, set, ran and the text the report prints.
watchdog	Only on a session the watchdog stopped: why (too-long, quiet, ceiling, ended-quiet or ended-alive), the finished stages the next session keeps, and the tokens and agent minutes it will do again.

Beside the records, the report reads <state folder>/findings.jsonl (one line per finding, written by foreman story end), check-runs.jsonl (every check run, reuse, wait and denied hand run), learner.jsonl and learning.jsonl. A record that is half written or not a record is skipped. Every file is in the state folder, never in your project’s git history; see Files. The records are kept on the state branch when you run with one (Run state on a branch), so a cloud run’s costs are there for foreman report on your machine.