MartinLoop
Keesan12/martin-loop
Controle e segurança para agentes de IA coding com orçamento, verificação e auditoria
Ver no GitHubPlano de controle open-source para agentes de IA que codificam, com limites de orçamento, gates de verificação, rastreamento de rollback e trilhas de auditoria. Envolve fluxos de Claude Code, Codex e Gemini com contratos explícitos de escopo, paradas seguras e provas review-ready.
Instalação
npx convez-ai Keesan12/martin-loop1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Limitar custos de tentativas de agentes de IA em tarefas de código
- Garantir verificação automática antes de aplicar mudanças em produção
- Gerar trilhas de auditoria e provas para revisão humana de trabalho gerado por IA
- Implementar políticas de segurança e bloquear operações arriscadas em repositórios
Veredito

Ferramenta madura e prática para empresas que usam agentes de IA em codificação, resolvendo o problema real de custos descontrolados e falta de auditoria. Integração MCP bem pensada e CLI acessível, mas requer setup de verificadores e políticas para máximo valor.
README
A tradução para o português deste README ainda está na fila.
MartinLoop
The open-source control plane for AI coding agents.
MartinLoop wraps Claude Code, Codex, Gemini, and MCP-aware agent workflows with budgets, verifier gates, policy checks, run receipts, and review-ready evidence.
Why MartinLoop
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.
Quick Start
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" --proof --verify "npm test"
npx -y martin-loop@latest dossier --latest
npx -y martin-loop@latest share --latest
start prints the first-run guided path. run auto-checks doctor, session-start, and preflight, then executes when the environment is ready. You can still run those commands directly when you want to inspect the governed checks first.
Inspect-first flow:
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 --latest writes three files into the selected run directory under share/: run-receipt.json, run-receipt.md, and proof-card.svg.
Release notes for the current root package: MartinLoop 0.3.3.
Run This Audit Yourself
Use this lane from a clean temp directory to verify the public CLI flow exactly as shipped:
npx -y martin-loop@0.3.2 --version
npx -y martin-loop@0.3.2 start
npx -y martin-loop@0.3.2 demo
cd martin-loop-demo
npm install
npx -y martin-loop@0.3.2 run "Summarize the demo workspace and prove tests still pass" --proof --verify "npm test" --json
npx -y martin-loop@0.3.2 dossier --latest --json
npx -y martin-loop@0.3.2 share --latest --json
For deterministic installs, pin the package line (martin-loop@0.3.2) or use martin-loop@latest. Plain npx martin-loop can resolve a stale local cache on some machines.
Expected share bundle outputs:
share/run-receipt.jsonshare/run-receipt.mdshare/proof-card.svg
What It Does
- 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, integrity state, and the next safe action.
martin share --latestturns the latest governed run into a local share bundle with a redacted JSON receipt, Markdown recap, and proof-card SVG.- MCP integration gives hosts one write-capable execution entrypoint plus richer planning, inspection, and review helpers.
How It Works
| 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, Gemini 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. Each loop record is locally signed (HMAC, per-runs-root key) and dossier/runs get/runs verify/challenge/badge report an integrity verdict (verified / tamper_detected / unsigned) so post-hoc edits to a record are detectable, not just inspectable. |
Trust Boundaries
- Cost and token outputs always include provenance (
actual,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 be
verifiedbefore a run is treated as trustworthy evidence for external review.
CLI
martin-loop doctor
martin-loop demo
martin-loop session-start [--host <claude|codex|gemini|generic>]
martin-loop phase status|contract|session-start|preflight|run [--execute]
martin-loop preflight <objective> [options]
martin-loop run <objective> [options]
martin-loop bench --suite <suiteId>
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>
martin-loop challenge [--loop-id <id> | --file <path> | --latest]
martin-loop share (--loop-id <id> | --file <path> | --latest) [--out-dir <path>]
martin-loop badge [--format svg|json] [--runs-dir <path>]
Examples below use npx martin-loop so they work without a global install. If you install martin-loop globally, the martin alias works too.
Use martin-loop share --latest after dossier when you want a redacted bundle you can hand to another person without sending raw run-store files.
More detail: CLI reference and configuration reference.
Benchmarks
MartinLoop ships a public deterministic benchmark workspace in benchmarks/ plus the installed-package bench command.
From an installed package:
npx martin-loop bench --suite under-3-challenge
npx martin-loop bench --suite ralphy-engineering-50
From a clean public clone:
pnpm install --frozen-lockfile
pnpm bench:build
pnpm bench:eval
pnpm bench:report:ralphy
Equivalent workspace-filter commands:
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.
MCP
Run the standalone MCP package directly:
npx -y @martinloop/mcp
Add 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/mcp
Generate 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-review
The root martin-loop package and the standalone @martinloop/mcp package move on separate version lines. The root package line here is 0.3.2; the current standalone MCP package is 0.3.1.
The public MCP release train labels are:
0.1.4operator foundation0.2.0cockpit expansion0.2.5public MCP package line0.2.7usability and review release0.3.0host adoption and onboarding release0.3.1review and handoff release
The standalone MCP registry/server identifier is io.github.Keesan12/martin-loop.
More detail: MCP setup, MCP tool reference, and MCP compatibility.
SDK
npm install martin-loop
import { MartinLoop, createClaudeCliAdapter } from "martin-loop";
const loop = new MartinLoop({
adapter: createClaudeCliAdapter({ workingDirectory: process.cwd() }),
defaults: {
workspaceId: "my-workspace",
projectId: "my-project",
budget: {
maxUsd: 3,
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);
The root SDK also exports createCodexCliAdapter, createGeminiCliAdapter, createDirectProviderAdapter, createOpenAiCompatibleAdapter, and createVerifierOnlyAdapter.
More detail: SDK reference and package map.
Examples
- Quickstart
- Examples
- Claude Code walkthrough
- Codex setup
- MCP setup
- MCP tool reference
- Agent run receipts
- GitHub Actions budget gate
- OpenCode-style adapter
Development
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:matrix:local
Standalone MCP validation:
pnpm --filter @martinloop/mcp lint
pnpm --filter @martinloop/mcp test
pnpm --filter @martinloop/mcp build
pnpm --filter @martinloop/mcp smoke:pack
pnpm --filter @martinloop/mcp smoke:published:pack
pnpm --filter @martinloop/mcp verify:release
Contributing
Issues, 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-feature
License
Apache-2.0. See LICENSE.