One estimate, one loop, one open record.

01 / the loop

Plan, record, outcome, finish.

The skill (loopmath skill install --target both) teaches Claude Code and Codex these steps. You can run the same commands by hand.

# 1. Plan: classify the task, then ask.
$ loopmath recommend --type bug_fix --repo acme/api \
    --feature size=s --feature lang=python --json > rec.json

# 2. Record: one run per workflow, one attempt per agent launched.
$ loopmath run start --task-file rec.json --config CFG --source usual --rec REC
$ loopmath run attempt --run RUN --piece implement --harness claude-code \
    --model MODEL --effort high --session UUID

# 3. Outcome: verdicts, scores, later events.
$ loopmath outcome --run RUN --signal tests=pass --kind verdict --tier verified

# 4. Finish: costs from the logs, a receipt, a refit.
$ loopmath run finish --run RUN

A pair runs your goal workflow and a pick worth trying on the same task, from the same base commit, in separate worktrees. A blinded referee picks the better change: loopmath outcome --slate SLT --prefer RUN --judge referee --blinded. Later events count too: an incident or revert is traced back to the run that made the commit with outcome --commit SHA.

02 / a recommendation

What recommend returns.

• Your usual workflow, found by onboard for this task type and repository, with its chance of an accepted result and its cost in tokens and dollars, each with a range.
• The success-cost curve: for each target chance of acceptance (50, 70, 80, 90, 95 and 99 percent), the cheapest workflow expected to reach it. A row is flagged when loopmath is not yet sure the workflow reaches that level.
• The goal: by default the lowest expected cost to an accepted result. With a score target (--target 'runtime_s<=200') you get the expected score and the chance of reaching it instead.
• Alternatives and two picks worth trying, each with its price, chance to beat the goal, saving per future similar run and payback.
• A suggested pair, and a one-paragraph message the orchestrator shows you as is.

expected cost to an accepted result = expected run cost + (1 − chance of acceptance) × cost of a rescue

The rescue is what a failed run costs you afterwards. By default it is your usual workflow repeated until a result is accepted: its cost divided by its chance. It can instead be a person's time, or nothing, as you configure it.

03 / how it learns

One estimate, shared across everything a run touches.

loopmath predicts two things for any workflow on any task: its cost, and its chance of an accepted result (and, when you set one, a score). Both are explained by the groups a run belongs to:

provider › model family › model › effort · harness · role · workflow shape › position · task type › repository › subtype · features

Each group's effect sits close to its parent's, with a spread learned from the data. Three things follow:

• Evidence is shared. A run teaches loopmath about every workflow that shares a group with it: a review run with one model informs other review runs with that model.
• New models start from their family. A model with no runs yet starts from its family's estimate, with a wider range, so a release does not reset what you know.
• Everything has a range. Sparse evidence means a wider band, not a missing answer.

loopmath ships with a starting estimate built from our own sweeps and experiments, so recommend answers before you have history. Your onboarded Claude Code and Codex sessions, then every run you record, move it. loopmath posterior --html shows what it believes at each level, with ranges.

04 / how a pick is priced

The gain of one trial, in dollars per future run.

For each candidate, loopmath imagines the outcomes of one trial run, updates its estimate under each, and asks how much the best choice for future similar tasks would improve on average. That average is the saving per future similar run. The price is the trial's expected cost now.

payback (runs) = price ÷ saving per future similar run

A candidate qualifies only when its saving is more than 1 percent of the goal's expected cost. The best-value pick has the fastest payback; the biggest-gain pick has the largest saving whose price fits under your cap (loopmath budget --usd X --period month). When no candidate qualifies, loopmath says nothing is worth trying.

05 / receipts

Predicted, then actual.

When a run starts from a recommendation, loopmath writes a receipt with what it predicted. When the run finishes, it fills in what happened: costs from the logs, the verdicts, and after the next fit, how the estimate moved. Receipts are how you check loopmath against itself.

06 / acceptance is your rule

Tests pass, a referee prefers, a score clears a bar.

By default a run is accepted when the task's tests pass. A rule can be a score target instead, and standing rules live in loopmath config. Every verdict carries an evidence tier (verified, reported, heuristic, asserted); missing evidence counts as the weakest.

07 / workflows are files

Six shapes ship; yours are TOML.

A workflow names its pieces, the artifacts between them, and its control: which gate decides, where a rejected change goes, how many rounds. With a setting for every piece, it is a configuration.

id = "implement_review_mine"
title = "Implement, then review"
edges = ["issue -> implement", "repo -> implement", "implement -> diff",
         "diff -> review", "review -> verdict"]

[control]
budget_rounds = 3             # rounds, counting the first

[[control.gates]]
after = "review"              # the review's verdict decides
on_fail = "implement"         # a rejected change goes back

[settings.implement]
harness = "claude-code"
model = "MODEL"
effort = "high"

Shortened. loopmath workflows validate FILE checks it, workflows diff compares it, recommend --workflow FILE considers it.

08 / OCP, the run format

One open JSON document per run.

Every recorded run is one document in OCP v0.3: the workflow graph, every attempt with its harness, model, effort, token counts by stream (input, cached input, cache creation, output, reasoning) and dollars, the artifacts, the signals and the receipt. The privacy profile is metadata_only: no prompt, completion or transcript text. The schema is published with a versioning promise; loopmath ocp validate checks a file.

OCP has its own site: what it is · the spec · examples · validation.

09 / local and private

What it touches, and what it never does.

• No command opens a network connection.
• Logs are opened read only. loopmath writes only to its store (~/.loopmath, or LOOPMATH_HOME) and to paths you name.
• Onboarding labels your sessions with a model you choose: through your claude or codex CLI, a local command such as Ollama, or none. loopmath never picks it for you.
• loopmath share --out FILE writes a reduced copy you can send us: task types, workflows, models, tokens, dollars and outcomes; repository names hashed; titles, paths, commands, session ids and commit shas removed. --preview prints exactly what would leave.

10 / the three views

Self-contained HTML, no server.

• Previous runs: loopmath runs --html. Every run with its workflow graph, costs, signals and receipt.
• Plans for a task: loopmath recommend ... --html. The candidates on a success-cost chart; click one for its graph and per-piece predictions.
• Current estimates: loopmath posterior --html. What loopmath believes at each level, with ranges.

11 / logs without recording

Useful before you record anything.

loopmath analyze prints cost per accepted run from the last 14 days of Claude Code and Codex logs, with an 80% band, and lists what it could not use and why. loopmath graph rebuilds which agent launched which and which session read what another wrote, as HTML, DOT or OCP.