MartinLoop
MartinLoop is an execution-control system for AI coding agents that adds budgets, stop conditions, rollback rules, and verifiable receipts to agent runs. It solves the problem of uncontrolled, expensive retry loops by enforcing a governed lifecycle from definition to verified handoff. It is for developers and teams using coding agents like Codex, Claude Code, or Gemini who need bounded, inspectable, and safe agent execution.
✨ Key features
- Enforces hard budget caps (USD, tokens, iterations) to stop runaway retries.
- Requires independent verifier commands (e.g., npm test) for completion.
- Provides run receipts, dossiers, and shareable proof bundles.
- Classifies failures into 13 canonical runtime classes for triage.
- Integrates with MCP hosts for a write-capable execution entrypoint.
- Supports multiple agent adapters: Claude, Codex, Gemini, and direct providers.
🎯 Use cases
- Govern coding-agent runs with budgets and iteration limits.
- Verify agent work with independent test commands before accepting completion.
- Audit agent behavior with run receipts and integrity checks.
- Compare agent outcomes across different models under one controlled flow.
- Prevent unsafe changes with rollback evidence and policy checks.
📦 Installation
🧰 Requirements: Requires Node.js and npm; no API keys or accounts mentioned in the README.
npx -y martin-loop@latest start
Or install globally:
npm install -g martin-loop@latest
🚀 Usage
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
npx -y martin-loop@latest dossier --latest
npx -y martin-loop@latest share --latest
⚠️ Good to know
MartinLoop does not replace Git, GitHub, CI, security scanners, observability platforms, code review, or the coding agent itself; it provides a governed execution record. A verifier proves only the checks it runs; VERIFIED is not a claim that code is bug-free or safe to merge.
❓ FAQ
What does MartinLoop do?
MartinLoop is an execution-control system for AI coding agents that adds budgets, stop conditions, rollback rules, and receipts to agent runs, making completion prove itself.
How do I install MartinLoop?
Run npx -y martin-loop@latest start or install globally with npm install -g martin-loop@latest.
What is a verifier?
A verifier is a command (e.g., npm test) that must pass with fresh evidence bound to the active run and workspace before a run can be marked VERIFIED.
What are the possible run outcomes?
The outcomes are VERIFIED when evidence supports the Definition of Done, STOPPED when a hard boundary ends the run, and NEEDS REVIEW when completion cannot be established.
📊 Repository
🤖 Overview, features, install steps and FAQ were generated from the project's README on Sep 4, 2026. Always check the original source before running commands.