The open-source control plane for AI coding agents.
MartinLoop wraps Claude Code, Codex, and MCP-aware agent workflows with budgets, verifier gates, policy checks, run receipts, and review-ready evidence.
AI coding agents are useful, but unbounded retry loops are expensive.
A task that looked like a $2.40 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.
Try MartinLoop in a disposable demo workspace:
npx martin-loop start
npx martin-loop tour
npx martin-loop demo
cd martin-loop-demo
npm install
npx martin-loop doctor
npx martin-loop session-start
npx martin-loop preflight "Summarize the demo workspace and prove tests still pass" --verify "npm test"
npx martin-loop run "Summarize the demo workspace and prove tests still pass" --proof --verify "npm test"
npx martin-loop dossier --lateststart and tour walk a new operator through the product flow. doctor, session-start, and preflight create the local receipts MartinLoop expects before a real governed run. If you intentionally need to bypass that local gate for a one-off run, use --unsafe-allow-unguarded-run explicitly.
Release notes for the current root package: MartinLoop 0.2.9.
- Budget caps stop the next attempt before a configured USD, token, or iteration limit is exceeded.
- Verifier gates require a real check, such as
npm test, before a run can count as complete. - Policy checks block unsafe verifier commands, risky path changes, and secret-like task inputs before execution.
- Run receipts capture stop reason, verifier evidence, budget posture, and next safe action.
- Local onboarding commands (
start,tour,guide,session-start) help operators adopt the governed flow without memorizing it. - MCP integration gives hosts one primary coding execution entrypoint plus richer planning, inspection, and review helpers.
| Layer | Purpose |
|---|---|
| Task contract | Objective, verifier plan, repo root, allowed paths, denied paths, acceptance criteria, workspace, project, and budget. |
| Policy and budget | Defaults come from martin.config.yaml; CLI flags can override them. Budget preflight blocks attempts that would exceed policy. |
| Agent adapters | Claude CLI, Codex CLI, direct-provider, and verifier-only adapters normalize execution results. |
| Safety and verification | Scope checks, verifier command checks, prompt integrity, and grounding decide whether work can continue. |
| Persistence | JSONL run records, evidence summaries, and repo-backed artifacts make every run inspectable later. |
martin-loop start [--host <codex|claude|gemini|generic>]
martin-loop tour [--host <codex|claude|gemini|generic>]
martin-loop guide [topic]
martin-loop doctor
martin-loop demo
martin-loop session-start [--host <claude|codex|generic>]
martin-loop phase status|contract|preflight|run [--execute]
martin-loop preflight <objective> [options]
martin-loop run <objective> [options]
martin-loop triage
martin-loop dossier (--latest | --loop-id <id> | --file <path>)
martin-loop runs list|get|attempt|verify ...
martin-loop mcp print-config --host <codex|claude|gemini|generic>
martin-loop mcp install --host <codex|claude|gemini|generic>
The local-first onboarding flow is:
martin-loop startmartin-loop tourmartin-loop doctormartin-loop session-startmartin-loop preflight ...martin-loop run ...martin-loop dossier --latest
More detail: CLI reference and configuration reference.
Run the standalone MCP package directly:
npx -y @martinloop/mcpAdd it to common hosts:
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/mcpGenerate host config from the root CLI:
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-reviewThe root martin-loop package and the standalone @martinloop/mcp package move on separate version lines. The root package is 0.2.9; the current standalone MCP package is 0.2.7.
More detail: MCP setup, MCP tool reference, and MCP compatibility.
npm install martin-loopimport { MartinLoop, createClaudeCliAdapter } from "martin-loop";
const loop = new MartinLoop({
adapter: createClaudeCliAdapter({ workingDirectory: process.cwd() }),
defaults: {
workspaceId: "my-workspace",
projectId: "my-project",
budget: {
maxUsd: 3.0,
softLimitUsd: 2.25,
maxIterations: 3,
maxTokens: 20_000,
},
},
});
const result = await loop.run({
task: {
title: "Fix auth regression",
objective: "Fix the failing auth regression tests",
verificationPlan: ["pnpm test"],
repoRoot: process.cwd(),
},
});
console.log(result.decision.status);More detail: SDK reference and package map.
- Quickstart
- Examples
- Claude Code walkthrough
- Codex setup
- MCP setup
- GitHub Actions budget gate
- OpenCode-style adapter
Requirements:
- Node.js 20+
- pnpm 10.x
git clone https://github.com/Keesan12/martin-loop.git
cd martin-loop
pnpm install --frozen-lockfile
pnpm lint
pnpm test
pnpm build
pnpm public:copy-scan
pnpm public:git-surface
pnpm oss:validate
pnpm public:smoke
pnpm release:validate-localIssues, bug reports, workflow feedback, and focused pull requests are welcome. Public-facing docs should stay concise, user-centered, and accurate.
git checkout -b feat/your-feature
pnpm lint
pnpm test
git commit -m "feat: describe what you built"
git push -u origin feat/your-featureApache-2.0. See LICENSE.