MartinLoop

When--modelis provided, MartinLoop passes it through unchanged. Without--model, the authenticated host runtime chooses its own default. MartinLoop does not inject a hidden fallback model.

MartinLoop is the execution-control system around coding agents. The coding agent still writes the code. MartinLoop governs the run and makes completion prove itself.

Use MartinLoop when a coding task needs one or more of these controls:

- preflight readiness before agent spend
- hard budget and iteration limits
- allowed or denied edit scope
- controlled retries and stop conditions
- independent verifier commands
- recovery and rollback evidence
- a finite completion decision
- run receipts, dossiers, history, failure classification, and post-run analysis
- one control layer across Codex, Claude Code, and other coding-agent environments

DEFINE -> PREFLIGHT -> CONTROL -> VERIFY -> RECOVER -> PROVE -> ANALYZE

The product-level flow isDefinition of Done -> Controlled Run -> Verified Handoff.

Teams should not need to stitch together a separate script or point tool for every part of coding-agent execution. MartinLoop connects the control path around the agent from preflight through post-run evidence.

MartinLoop does not replace Git, GitHub, CI, dedicated security scanners, observability platforms, code review, or the coding agent itself. It gives those workflows one governed execution record to inspect.

AI coding agents are useful, but unbounded retry loops are expensive.

A task that looked like a small fix can become dozens of attempts, a blown token budget, and a diff nobody trusts. MartinLoop gives every run an explicit contract: objective, verifier, budget, scope, receipts, and a clear stop condition.

Use it when AI coding work needs to stay bounded, inspectable, and safe to review before it becomes expensive or destructive.

- It turns agent behavior into inspectable run receipts you can actually review.
- It enforces hard stop conditions before runaway retries spend more money.
- It adds rollback-aware rules so failed attempts do not silently leave unsafe changes behind.
- It helps teams compare outcomes across agents under one governed flow.

Teams use MartinLoop when they need governed agent execution that can be reviewed and trusted.

npx -y martin-loop@latest start npx -y martin-loop@latest demo cd martin-loop-demo npm install npx -y martin-loop@latest run "Summarize the demo workspace and prove tests still pass" --verify "npm test" --budget-usd 2 --max-iterations 1

Try MartinLoop in a disposable demo workspace:

npx -y martin-loop@latest start npx -y martin-loop@latest demo npx -y martin-loop@latest --version cd martin-loop-demo npm install npx -y martin-loop@latest run "Summarize the demo workspace and prove tests still pass" --verify "npm test" --budget-usd 2 --max-iterations 1 npx -y martin-loop@latest dossier --latest npx -y martin-loop@latest share --latest

npm install -g martin-loop martin-loop --version

If this flow is useful, open an issue with feedback so we can keep improving the public experience.

startprints the first-run guided path.runauto-checksdoctor,session-start, andpreflight, then executes when the environment is ready. Use--proofonly when you intentionally want an explicit no-spend lane.

npx -y martin-loop@latest doctor npx -y martin-loop@latest session-start npx -y martin-loop@latest preflight "Summarize the demo workspace and prove tests still pass" --verify "npm test"

share --latestwrites three files into the selected run directory undershare/:run-receipt.json,run-receipt.md, andproof-card.svg.

MartinLoop's terminal presentation is built around the governed lifecycle, not around a single verifier command.

Governed Run Planshows the configured finish line before work starts, including the task, budget posture, verifier plan, scope, and execution boundaries.

Controlled Runkeeps the coding agent working inside those boundaries while MartinLoop tracks attempts, cost, stop conditions, and recovery state.

Verified Handoffcloses the loop with one authoritative outcome:

- VERIFIEDwhen the configured evidence supports the Definition of Done
- STOPPEDwhen a configured hard boundary ends the run
- NEEDS REVIEWwhen completion cannot be established from the available evidence

The handoff can include verifier steps, scope state, attempt count, cost provenance, unresolved evidence, recovery state, receipt integrity, and the next safe action. The exact fields depend on what the run actually established.

MartinLoop turns an AI coding run into an inspectable execution record: budget used, verifier result, changed files, rollback evidence, and final receipt.

Ungoverned agents can retry until cost and scope drift. MartinLoop adds budget caps, verifier gates, and audit evidence so the run has a clear stop condition.

Long governed runs do not have to mean staring at a spinner. In an interactive terminal, MartinLoop Arcade can be offered while the coding agent continues working in the background.

Arcade is presentation-only. It cannot change the agent, budget, verifier, policy decision, run outcome, or receipt evidence. It stays out of JSON, CI, non-interactive, and other machine-readable execution paths.

Use--arcadeto offer Arcade immediately for a supported interactive run, or--no-arcadeto suppress it for that run.

Proof receipts are local share bundles for governed AI coding runs. They show the task, spend, budget, verifier result, receipt integrity, and any evidence boundary that should not be rounded into confidence.

This real governed run spent$0.51against a$3.00budget. The verifier passed and the receipt integrity was signed, but the proof stayed atEVIDENCE_BOUNDARYbecause rollback evidence was not recorded.

Generate your own receipt after a governed run:

npx -y martin-loop@latest run "Summarize the demo workspace and prove tests still pass" --proof --verify "npm test" npx -y martin-loop@latest runs verify --latest npx -y martin-loop@latest share --latest

Use this lane from a clean temp directory to verify the public CLI flow exactly as shipped:

npx -y martin-loop@0.5.5 --version npx -y martin-loop@0.5.5 start npx -y martin-loop@0.5.5 demo cd martin-loop-demo npm install npx -y martin-loop@0.5.5 run "Summarize the demo workspace and prove tests still pass" --verify "npm test" --budget-usd 2 --max-iterations 1 --json npx -y martin-loop@0.5.5 dossier --latest --json npx -y martin-loop@0.5.5 share --latest --json

For deterministic installs, pin the package line (martin-loop@0.5.5) or usemartin-loop@latest. Plainnpx martin-loopcan resolve a stale local cache on some machines.

- share/run-receipt.json
- share/run-receipt.md
- share/proof-card.svg

The point is not that every governed run is always cheaper. The point is that every run becomes inspectable and enforceable: budget policy, verifier result, stop reason, and evidence are explicit.

For a deterministic public repro lane, use the benchmark workspace and compare governed execution to unbounded retry behavior:

- npx martin-loop bench --suite under-3-challenge
- npx martin-loop bench --suite ralphy-engineering-50

A Ralph-style loop is the failure mode where an AI coding agent keeps trying without knowing when continuing is unsafe, uneconomical, or unlikely to succeed.

MartinLoop keeps the useful part of the loop, then adds brakes:

- stop before budget overspend
- classify unsafe or invalid actions before execution
- write an audit record for every attempt
- preserve rollback and verifier evidence for review
- reduce runaway context growth with compact run summaries

Public governed runs use one canonical taxonomy: the 13 runtimeFailureClassvalues from@martin/contracts.

- Cost and token outputs always include provenance (actual,calculated,estimated, orunavailable).
- For Codex specifically, MartinLoop reports authoritative usage only when the host exposes it; otherwise MartinLoop labels usage as estimated and avoids presenting it as settled accounting.
- Receipt integrity must beverifiedbefore a run is treated as trustworthy evidence for external review.

MartinLoop ships a public deterministic benchmark workspace inbenchmarks/plus the installed-packagebenchcommand.

npx martin-loop bench --suite under-3-challenge npx martin-loop bench --suite ralphy-engineering-50

pnpm install --frozen-lockfile pnpm bench:build pnpm bench:eval pnpm bench:report:ralphy

pnpm --filter @martin/benchmarks build pnpm --filter @martin/benchmarks test pnpm --filter @martin/benchmarks eval pnpm --filter @martin/benchmarks report:ralphy

The installed-package command reads the shipped public fixtures. The repo-clone workflow runs the public benchmark workspace directly.

Run the standalone MCP package directly:

codex mcp add martin-loop -- npx -y @martinloop/mcp claude mcp add --transport stdio --scope user martin-loop -- npx -y @martinloop/mcp claude mcp add --transport stdio --scope user martin-loop -- cmd /c npx -y @martinloop/mcp

npx martin-loop mcp print-config --host codex --transport stdio --profile minimal npx martin-loop mcp print-config --host claude --transport stdio --profile diagnostic npx martin-loop mcp print-config --host gemini --transport stdio --profile full-local npx martin-loop mcp print-config --host generic --transport stdio --profile github-review