MartinLoop — Summary

Slug: martinloop
GitHub: https://github.com/Keesan12/Martin-Loop
Stars: 22
License: Apache-2.0
Language: TypeScript (Node.js 20+)
Status: Active (last commit 2026-05-26); NVIDIA Inception Program accepted

What It Is

MartinLoop is a governance control plane for AI coding agent loops. It wraps Claude Code, Codex, and custom agent runs with hard budget caps, policy checks, verifier gates, rollback evidence, and JSONL audit records.

It does not run code itself — it governs the "Ralph Loop" (the failure mode where an AI coding agent keeps retrying without a stop condition, burning budget with no audit trail).

Core Value Proposition

"AI coding accountability: completes good work, refuses unsafe work, stops uneconomical work."

Same task, same starting state: MartinLoop completes in one verified attempt at $2.30. Uncontrolled loop retries 4× at $5.20 with no audit trail (README benchmark).

Five-Layer Architecture

1. Task Contract — Objective, verifier plan, repo root, allowed/denied paths, acceptance criteria, budget
2. Policy & Budget — martin.config.yaml + CLI flags; budget preflight rejects attempts before execution
3. Agent Adapters — Claude CLI, Codex CLI, direct-provider, stub adapters normalize results
4. Safety & Verification — Verifier commands, file scope, approval-boundary changes, secret scan, grounding
5. Persistence — JSONL records at ~/.martin/runs/<workspaceId>.jsonl

Key Capabilities

• Budget hard caps (maxUsd, softLimitUsd, maxIterations, maxTokens)
• 11-class failure taxonomy (hallucination, test regression, scope creep, repo grounding failure, env mismatch, budget pressure, etc.)
• Red-Blue adversarial testing (6 probes, 3 risk tiers)
• Context injection detection (authority inversion, instruction override, identity redefinition)
• Rollback evidence capture
• Context distillation for subsequent attempts
• JSONL run records (inspectable, resumable)

Packages

• martin-loop — root npm package (CLI + SDK)
• @martin/contracts — shared types
• @martin/core — runtime, policy engine, safety leash
• @martin/adapters — Claude CLI, Codex CLI, direct-provider, stub
• @martin/cli — CLI implementation
• @martinloop/mcp — MCP server (11 tools, 12 resources, 10 prompts)

MartinLoop — Overview

Origin and Positioning

MartinLoop was created by Keesan (keesan@martinloop.com) and accepted into the NVIDIA Inception Program. The README opens with a concrete failure story: "$2.40 estimated, $65 billed — 47 attempts, no hard stop, no rollback, no audit trail, nothing merged."

The project frames autonomous AI coding loops as having an unsolved failure mode — the "Ralph Loop" — and positions MartinLoop as the control layer that stops that failure before damage happens.

Website: https://martinloop.com

The Ralph Loop Concept

The "Ralph Loop" names the failure mode where an AI coding agent keeps retrying work without knowing when to stop. Symptoms:

• No hard budget cap
• No signed evidence layer
• No pre-execution control system
• Knows how to keep trying, does not know when continuing is unsafe, uneconomical, or impossible

MartinLoop governs this by:

1. Stopping the next attempt before budget overspend
2. Classifying unsafe/invalid actions before execution
3. Appending a JSONL audit record for every attempt
4. Rolling back failed runs instead of leaving broken state
5. Reducing runaway token growth with context distillation

Freemium Model

Philosophy

MartinLoop explicitly does NOT try to replace agent patterns — it makes those patterns safe to run. The distinction is important: it is a governance layer, not an agent platform.

Quote: "AI coding agents are useful. Unbounded retry loops are not."

11-Class Failure Taxonomy

MartinLoop classifies failures into 11 named classes:

1. Hallucination
2. Test regression
3. Scope creep
4. Repo grounding failure
5. Environment mismatch
6. Budget pressure
7. Context poisoning (detected before admission)
8. Authority inversion
9. Instruction override
10. Identity redefinition
11. (Additional classes documented in codebase)

This taxonomy distinguishes real success from unsafe, invalid, or terminal behavior.

Red-Blue Testing

Six deterministic adversarial probes before a patch is accepted:

1. Assertion deletion
2. Silent reverts
3. Context poisoning
4. Budget self-reporting
5. Grounding evasion
6. (Additional probe)

Three risk tiers:

• baseline — default
• high_risk — stricter
• release_critical — adds a Haiku model call

A single block-severity finding rejects the patch.

MartinLoop — Architecture

Distribution

• npm package: martin-loop (root facade)
• MCP package: @martinloop/mcp@0.2.5 (standalone)
• Install: npx martin-loop demo or npm install martin-loop

Package Structure

Martin-Loop/
├── packages/
│   ├── adapters/         # @martin/adapters — Claude CLI, Codex CLI, direct-provider, stub
│   ├── cli/              # @martin/cli — CLI implementation
│   │   └── src/
│   │       ├── bin/martin.ts
│   │       ├── mcp-config.ts
│   │       ├── persistence.ts
│   │       ├── run-store.ts
│   │       └── ux.ts
│   ├── contracts/        # @martin/contracts — shared types (loops, policy, governance, budget)
│   ├── core/             # @martin/core — runtime, policy engine, safety leash, grounding
│   └── mcp/              # @martinloop/mcp — MCP server
│       └── src/
│           ├── tools/    # 11+ tool handlers
│           ├── resources.ts
│           ├── prompts.ts
│           └── server.ts
├── martin.config.example.yaml
├── AGENTS.md
└── docs/
    └── oss/
        ├── QUICKSTART.md
        ├── RALPH-LOOP-SAFETY.md
        ├── MCP-FOR-AI-AGENTS.md
        └── CLAUDE-CODE-WALKTHROUGH.md

Five-Layer Runtime

[Task Contract Input]
        ↓
[Policy & Budget]  ← martin.config.yaml + CLI flags
  - maxUsd / softLimitUsd / maxIterations / maxTokens
  - destructiveActionPolicy
  - verifierRules
        ↓
[Safety Leash]  ← pre-execution checks
  - verifier command safety
  - file scope validation
  - secret-like values scan
  - context injection detection (authority inversion, instruction override)
        ↓
[Agent Adapter]  ← pluggable
  - Claude CLI adapter
  - Codex CLI adapter
  - Direct-provider adapter
  - Stub adapter (testing)
        ↓
[Verifier Gate]  ← post-execution checks
  - Run verifier commands (pnpm test, pnpm lint, etc.)
  - Red-Blue adversarial probes (6 probes, 3 tiers)
  - Failure taxonomy classification (11 classes)
        ↓
[Persistence]
  - JSONL records: ~/.martin/runs/<workspaceId>.jsonl
  - Rollback boundaries + restore outcomes
  - Context distillation for next attempt

State Files

• ~/.martin/runs/<workspaceId>.jsonl — JSONL run records (append-only)
• martin.config.yaml (project-local) — budget caps and verifier rules
• martin.config.example.yaml — template with all configurable fields

MCP Release Train

Adapter Pattern

Each adapter normalizes an agent's execution results into @martin/contracts types, allowing the core runtime to operate identically regardless of whether Claude Code, Codex, or a custom agent is running:

// Claude Code adapter
const loop = new MartinLoop({
  adapter: createClaudeCliAdapter({ workingDirectory: process.cwd() })
});

// Codex adapter
const loop = new MartinLoop({
  adapter: createCodexCliAdapter({ workingDirectory: process.cwd() })
});

MartinLoop — Components

CLI Binary: martin-loop

Install: npm install -g martin-loop

CLI Subcommands (inferred from docs/source)

Key CLI Flags

• --max-usd <n> — Hard USD budget cap
• --soft-limit-usd <n> — Early warning threshold
• --max-iterations <n> — Max retry iterations
• --max-tokens <n> — Max token budget
• --verify <cmd> — Override verifier commands
• --policy-profile <name> — Policy profile (balanced, strict, etc.)
• --allowed-paths <glob> — Restrict file scope
• --denied-paths <glob> — Explicitly deny file access

MCP Server: @martinloop/mcp

Install: npx -y @martinloop/mcp

Transport: stdio

MCP Tools (11)

MCP Resources (12)

MCP Prompts (10)

martin_start, martin_preflight, martin_triage, martin_resume, martin_prove, martin_release_check, martin_governed_coding_kickoff, martin_debug_failed_run, martin_publish_readiness_review, martin_triage_run_store

Config Schema: martin.config.yaml

policyProfile: balanced
budget:
  maxUsd: 8                   # Hard cost cap
  softLimitUsd: 5             # Early warning threshold
  maxIterations: 3            # Max loop iterations
  maxTokens: 20000            # Max token budget
governance:
  destructiveActionPolicy: approval   # approval | block | allow
  telemetryDestination: control-plane
  verifierRules:
    - pnpm test
    - pnpm lint

SDK Interface

import { MartinLoop, createClaudeCliAdapter } from 'martin-loop';

const loop = new MartinLoop({
  adapter: createClaudeCliAdapter({ workingDirectory: process.cwd() }),
  policy: {
    maxUsd: 5,
    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()
  }
});

Integration: Claude Code

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

Integration: Codex

codex mcp add martin-loop -- npx -y @martinloop/mcp

MartinLoop — Uniqueness and Positioning

Differs from Seeds

MartinLoop occupies a unique niche in this batch: it is not a multi-agent orchestrator. It is a governance wrapper for single-agent coding loops. This makes it architecturally different from every other framework in the batch.

Versus claude-flow (parallel multi-agent orchestration): claude-flow maximizes parallelism and throughput. MartinLoop maximizes trust, auditability, and cost control on a single agent run.

Versus bernstein (Python scheduler with HMAC audit): Bernstein orchestrates a pipeline of specialized agents (manager, architect, worker, QA) with deterministic scheduling and compliance-grade HMAC audit logs. MartinLoop governs a single agent loop with budget caps, but does not orchestrate multi-agent pipelines.

Versus taskmaster-ai (task decomposition and tracking): Taskmaster manages tasks but does not execute them or govern the execution loop's budget. MartinLoop governs execution but does not decompose tasks.

Versus stoneforge (Director/Worker/Steward hierarchy): Stoneforge is a full multi-agent workforce platform. MartinLoop is a governance control plane that wraps one agent at a time.

Distinctive Features

1. Named failure taxonomy (11 classes) — the only framework that classifies why a loop failed into named categories. No other seed or batch framework has an explicit failure taxonomy.

2. Red-Blue adversarial testing — 6 deterministic adversarial probes (assertion deletion, silent reverts, context poisoning, budget self-reporting, grounding evasion) that run before a patch is accepted. No other framework reviewed has adversarial probe suites.

3. Budget-as-first-class-concept — maxUsd, softLimitUsd, maxIterations, maxTokens are all configurable and enforced as hard stops. Cost governance at this granularity is not present in any seed framework.

4. Context injection detection — scans for authority inversion, instruction override, identity redefinition in prompts before admission. Unique security posture.

5. JSONL audit records — every attempt produces an append-only JSONL record with lifecycle state, budget consumption, failure classification, verifier evidence, and rollback boundary. The closest seed is Bernstein's HMAC-chained audit (more compliance-grade); MartinLoop's is simpler but more inspection-friendly.

6. Ralph Loop naming — MartinLoop has done conceptual work to name the failure mode it solves. "Ralph Loop" gives practitioners a vocabulary for the ungoverned retry failure mode.

Positioning

MartinLoop targets individual developers and teams who run autonomous coding loops (Claude Code, Codex) unattended and have experienced uncontrolled retries burning budget. It is a safety net/governance add-on, not a replacement for agent frameworks.

The NVIDIA Inception Program acceptance suggests commercial ambitions beyond the OSS tier.

Observable Failure Modes

1. Governance overhead — wrapping every agent run with preflight, safety leash, and verifier adds latency and setup complexity. Teams may skip governance for "simple" tasks and miss the protection.
2. Single-agent only (OSS) — no multi-agent coordination. Teams wanting parallel execution must look elsewhere.
3. No web UI (free tier) — CLI-only for OSS users; run inspection requires martin-loop inspect commands rather than a dashboard.
4. 22 stars — small community; early stage; docs are good but ecosystem is minimal.
5. Node.js 20+ required — excludes some environments.