Skip to content
Back to search

martinloop

MarketplaceWorks with Claude CodeGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/keesan12--martin-loop/badge.svg)](/listings/keesan12--martin-loop)

HTML

<a href="/listings/keesan12--martin-loop"><img src="/api/listings/keesan12--martin-loop/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Try MartinLoop in a disposable demo workspace:

npx -y martin-loop@latest enable --engine codex
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

Optional global install:

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.

`start` prints the first-run guided path. `run` auto-checks `doctor`, `session-start`, and `preflight`, then executes when the environment is ready. Use `--proof` only when you intentionally want an explicit no-spend lane.

Inspect-first flow:

npx -y martin-loop@latest enable --engine codex
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 MartinLoop 0.6.5: [MartinLoop 0.6.5](./docs/release/OSS-0.6.5-RELEASE-NOTES.md).

Release notes for MartinLoop 0.6.6: [MartinLoop 0.6.6](./docs/release/OSS-0.6.6-RELEASE-NOTES.md).

Release notes for MartinLoop 0.6.7: [MartinLoop 0.6.7](./docs/release/OSS-0.6.7-RELEASE-NOTES.md).

Release notes for MartinLoop 0.6.8: [MartinLoop 0.6.8](./docs/release/OSS-0.6.8-RELEASE-NOTES.md).

Release notes for MartinLoop 0.7.0: [MartinLoop 0.7.0](./docs/release/OSS-0.7.0-RELEASE-NOTES.md).

Release notes for MartinLoop 0.7.1: [MartinLoop 0.7.1](./docs/release/OSS-0.7.1-RELEASE-NOTES.md).

Release notes for MartinLoop 0.8.0: [MartinLoop 0.8.0](./docs/release/OSS-0.8.0-RELEASE-NOTES.md).

Release notes for MartinLoop 0.8.1: [MartinLoop 0.8.1](./docs/release/OSS-0.8.1-RELEASE-NOTES.md).

Release notes for MartinLoop 0.8.2: [MartinLoop 0.8.2](./docs/release/OSS-0.8.2-RELEASE-NOTES.md).

Release notes for MartinLoop 0.8.3: [MartinLoop 0.8.3](./docs/release/OSS-0.8.3-RELEASE-NOTES.md).

Release notes for MartinLoop 0.8.4: [MartinLoop 0.8.4](./docs/release/OSS-0.8.4-RELEASE-NOTES.md).

Release notes for MartinLoop 0.8.5: [MartinLoop 0.8.5](./docs/release/OSS-0.8.5-RELEASE-NOTES.md).

Release notes for MartinLoop 0.8.6: [MartinLoop 0.8.6](./docs/release/OSS-0.8.6-RELEASE-NOTES.md).

Release notes for MartinLoop 0.8.7: [MartinLoop 0.8.7](./docs/release/OSS-0.8.7-RELEASE-NOTES.md).

Release notes for MartinLoop 0.8.8: [MartinLoop 0.8.8](./docs/release/OSS-0.8.8-RELEASE-NOTES.md).

Release notes for MartinLoop 0.8.9: [MartinLoop 0.8.9](./docs/release/OSS-0.8.9-RELEASE-NOTES.md).

Release notes for MartinLoop 0.9.0: [MartinLoop 0.9.0](./docs/release/OSS-0.9.0-RELEASE-NOTES.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "martinloop",
  3. "owner": {
  4. "name": "MartinLoop",
  5. "email": "keesan@martinloop.com"
  6. },
  7. "strict": true,
  8. "plugins": [
  9. {
  10. "name": "martinloop",
  11. "source": "./plugins/martinloop",
  12. "description": "One system around coding agents to run, verify, recover, and hand off software work.",
  13. "version": "0.9.0",
  14. "author": {
  15. "name": "MartinLoop contributors"
  16. }
  17. }
  18. ]
  19. }
README.md · README · 706 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MartinLoop
  2. **Give coding agents more work. Watch them less. Ship more.**
  3. MartinLoop lets you give coding agents real software jobs without babysitting every step.
  4. Your coding agent still writes the code. MartinLoop keeps the job focused, bounded, and accountable — with limits, stop conditions, verification, recovery, and a clear outcome when the run ends.
  5. <div align="center">
  6. <img src="./docs/assets/martinloop-logo.png" alt="MartinLoop" width="260">
  7. **Trust your coding agents with real work.**
  8. Built from thousands of agent runs where the problem was not just intelligence — it was whether you could give the agent a real job and confidently walk away.
  9. **Measure your loop tax:** `npx -y martin-loop@latest audit`
  10. **Get started:** `npx -y martin-loop@latest start`
  11. **Try the demo:** `npx -y martin-loop@latest demo`
  12. [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square&logo=apache)](./LICENSE)
  13. [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square&logo=typescript&logoColor=white)](./tsconfig.base.json)
  14. [![Node](https://img.shields.io/badge/node-%3E%3D20-3c873a?style=flat-square&logo=nodedotjs&logoColor=white)](#quick-start)
  15. [![npm version](https://img.shields.io/npm/v/martin-loop?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/martin-loop)
  16. [![npm downloads](https://img.shields.io/npm/dm/martin-loop?style=flat-square&label=downloads)](https://www.npmjs.com/package/martin-loop)
  17. MartinLoop is part of the NVIDIA Inception program.
  18. <br>
  19. <picture>
  20. <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/nvidia-inception-program.png">
  21. <img src="./docs/assets/nvidia-inception-program-light.png" alt="NVIDIA Inception Program logo" width="280">
  22. </picture>
  23. </div>
  24. ## Start Here
  25. **Audit first** — run `npx -y martin-loop@latest audit` to see how much API-equivalent Claude Code spend went into fix-and-retry loops. Add `--offline` for zero network access or `--share` for a shareable summary.
  26. **Install / onboard** — run `npx -y martin-loop@latest start`, or install it globally with `npm install -g martin-loop@latest`.
  27. **Governed run** — define an objective, verifier, budget, and iteration cap with `martin run`.
  28. **Verifier** — completion requires fresh verifier evidence bound to the active run and workspace. A configured verifier proves only the checks it runs; `VERIFIED` is not a claim that the code is bug-free or automatically safe to merge.
  29. **Budget** — set a hard spend ceiling with `--budget-usd` and an attempt ceiling with `--max-iterations`.
  30. **Receipts** — inspect the latest result with `martin dossier --latest` and validate stored integrity with `martin runs verify --latest`.
  31. **Hosted sync (optional)** — governed work is local-first. Configure `MARTIN_API_TOKEN` and `MARTIN_TELEMETRY_ENDPOINT`, then use `martin sync status` and `martin sync flush` to send preserved evidence to a dashboard later. See the [quickstart](./docs/getting-started/quickstart.md#optional-hosted-dashboard-sync).
  32. **MCP** — install `@martinloop/mcp@latest` in a supported host or generate host configuration with `martin mcp print-config`.
  33. **Documentation** — continue with the [quickstart](./docs/getting-started/quickstart.md), [CLI reference](./docs/reference/cli.md), or [MCP setup](./docs/getting-started/mcp.md).
  34. When `--model` is provided, MartinLoop passes it through unchanged. Without `--model`, the authenticated host runtime chooses its own default. MartinLoop does not inject a hidden fallback model.
  35. ## For AI Agents
  36. MartinLoop is the system around the coding job.
  37. The coding agent still writes the code. MartinLoop keeps the job, limits, verification, recovery, outcome, and history consistent around the work.
  38. Use MartinLoop when a coding task needs:
  39. - clear job and success criteria
  40. - preflight readiness before agent spend
  41. - hard budget and iteration limits
  42. - allowed or denied edit scope
  43. - controlled retries and stop conditions
  44. - independent verifier commands
  45. - recovery and rollback evidence
  46. - a finite completion decision
  47. - run receipts, dossiers, history, failure classification, and post-run analysis
  48. - one consistent workflow across supported coding-agent runtimes
  49. Canonical lifecycle:
  50. ```text
  51. DEFINE
  52. -> PREFLIGHT
  53. -> CONTROL
  54. -> VERIFY
  55. -> RECOVER
  56. -> PROVE
  57. -> ANALYZE
  58. ```
  59. The product-level flow is **Definition of Done -> Controlled Run -> Verified Handoff**.
  60. For machine-readable context start with [`llms.txt`](./llms.txt), [`llms-full.txt`](./llms-full.txt), and [MartinLoop for AI Agents](./docs/for-agents.md).
  61. ## One System Around the Run
  62. 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.
  63. | Stage | MartinLoop role |
  64. | --- | --- |
  65. | Define | Capture the objective, verifier, budget, scope, and finish line. |
  66. | Preflight | Check readiness and required workflow evidence before agent spend. |
  67. | Control | Enforce budgets, attempts, path boundaries, policy, and stop conditions while the coding agent works. |
  68. | Verify | Run configured checks and bind the evidence to the active run and workspace. |
  69. | Recover | Preserve recovery and rollback state when another attempt or human review is required. |
  70. | Prove | Produce the authoritative `VERIFIED`, `STOPPED`, or `NEEDS REVIEW` handoff plus receipts. |
  71. | Analyze | Inspect run history, cost provenance, failure classes, dossiers, and shareable evidence after execution. |
  72. 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.
  73. ### Change the worker. Keep the job.
  74. MartinLoop is model-agnostic by design. The job, limits, verification, recovery, and outcome are separate from the worker underneath.
  75. Native coding-agent CLIs and OpenAI-compatible model runtimes use different execution paths, so MartinLoop only describes a worker as fully supported when that execution path has been publicly released and validated.
  76. ## Why MartinLoop
  77. AI coding agents can create more software than ever. The problem is trusting them with bigger jobs without turning yourself into their full-time manager.
  78. Agents drift. They retry. They break unrelated things. They say "done" too early. And a run that was supposed to save time can create even more work to review.
  79. MartinLoop keeps the job accountable outside the agent itself: clear boundaries, hard limits, configured checks, recovery information, and an explicit outcome.
  80. The goal is simple:
  81. **Give the agent more responsibility without giving it unlimited freedom.**
  82. ## Why Teams Adopt MartinLoop
  83. - **Less babysitting** — give agents larger jobs without watching every step.
  84. - **Clear boundaries** — keep scope, attempts, and spend inside the limits you set.
  85. - **Checks before "done"** — configured verification decides whether the evidence passed.
  86. - **Understand failures** — know why the run stopped instead of digging through logs.
  87. - **Recover cleanly** — preserve enough evidence to retry, repair, roll back, or hand off.
  88. - **One workflow across agents** — keep the job consistent as the worker underneath changes.
  89. **More software. Less supervision.**
  90. ## See Your Loop Tax
  91. Before changing your workflow, measure it:
  92. ```sh
  93. npx -y martin-loop@0.9.0 audit
  94. ```
  95. MartinLoop reads Claude Code session history locally and reports how much API-equivalent agent spend happened inside fix-and-retry loops, how often verifier commands failed, the longest retry chain, and sessions that ended red. Session contents stay local. Use `--offline` to disable even the public pricing lookup, and `--share` to create a screenshot-ready SVG plus Markdown summary.
  96. Then put limits around the next run:
  97. ```sh
  98. npx -y martin-loop@0.9.0 enable --engine codex
  99. npx -y martin-loop@0.9.0 run "<task>" --verify "npm test" --budget-usd 2 --max-iterations 3
  100. ```
  101. ## 2-Minute Install Path
  102. If MartinLoop detects more than one supported coding-agent runtime, save the one you want to use before the first governed run. For example:
  103. ```sh
  104. npx -y martin-loop@latest enable --engine codex
  105. ```
  106. Replace `codex` with `claude` or `gemini` when that is your intended runtime.
  107. ```sh
  108. npx -y martin-loop@latest start
  109. npx -y martin-loop@latest demo
  110. cd martin-loop-demo
  111. npm install
  112. npx -y martin-loop@latest run "Summarize the demo workspace and prove tests still pass" --verify "npm test" --budget-usd 2 --max-iterations 1
  113. ```
  114. ## Quick Start
  115. Try MartinLoop in a disposable demo workspace:
  116. ```sh
  117. npx -y martin-loop@latest enable --engine codex
  118. npx -y martin-loop@latest start
  119. npx -y martin-loop@latest demo
  120. npx -y martin-loop@latest --version
  121. cd martin-loop-demo
  122. npm install
  123. npx -y martin-loop@latest run "Summarize the demo workspace and prove tests still pass" --verify "npm test" --budget-usd 2 --max-iterations 1
  124. npx -y martin-loop@latest dossier --latest
  125. npx -y martin-loop@latest share --latest
  126. ```
  127. Optional global install:
  128. ```sh
  129. npm install -g martin-loop
  130. martin-loop --version
  131. ```
  132. If this flow is useful, open an issue with feedback so we can keep improving the public experience.
  133. `start` prints the first-run guided path. `run` auto-checks `doctor`, `session-start`, and `preflight`, then executes when the environment is ready. Use `--proof` only when you intentionally want an explicit no-spend lane.
  134. Inspect-first flow:
  135. ```sh
  136. npx -y martin-loop@latest enable --engine codex
  137. npx -y martin-loop@latest doctor
  138. npx -y martin-loop@latest session-start
  139. npx -y martin-loop@latest preflight "Summarize the demo workspace and prove tests still pass" --verify "npm test"
  140. ```
  141. `share --latest` writes three files into the selected run directory under `share/`: `run-receipt.json`, `run-receipt.md`, and `proof-card.svg`.
  142. Release notes for MartinLoop 0.6.5: [MartinLoop 0.6.5](./docs/release/OSS-0.6.5-RELEASE-NOTES.md).
  143. Release notes for MartinLoop 0.6.6: [MartinLoop 0.6.6](./docs/release/OSS-0.6.6-RELEASE-NOTES.md).
  144. Release notes for MartinLoop 0.6.7: [MartinLoop 0.6.7](./docs/release/OSS-0.6.7-RELEASE-NOTES.md).
  145. Release notes for MartinLoop 0.6.8: [MartinLoop 0.6.8](./docs/release/OSS-0.6.8-RELEASE-NOTES.md).
  146. Release notes for MartinLoop 0.7.0: [MartinLoop 0.7.0](./docs/release/OSS-0.7.0-RELEASE-NOTES.md).
  147. Release notes for MartinLoop 0.7.1: [MartinLoop 0.7.1](./docs/release/OSS-0.7.1-RELEASE-NOTES.md).
  148. Release notes for MartinLoop 0.8.0: [MartinLoop 0.8.0](./docs/release/OSS-0.8.0-RELEASE-NOTES.md).
  149. Release notes for MartinLoop 0.8.1: [MartinLoop 0.8.1](./docs/release/OSS-0.8.1-RELEASE-NOTES.md).
  150. Release notes for MartinLoop 0.8.2: [MartinLoop 0.8.2](./docs/release/OSS-0.8.2-RELEASE-NOTES.md).
  151. Release notes for MartinLoop 0.8.3: [MartinLoop 0.8.3](./docs/release/OSS-0.8.3-RELEASE-NOTES.md).
  152. Release notes for MartinLoop 0.8.4: [MartinLoop 0.8.4](./docs/release/OSS-0.8.4-RELEASE-NOTES.md).
  153. Release notes for MartinLoop 0.8.5: [MartinLoop 0.8.5](./docs/release/OSS-0.8.5-RELEASE-NOTES.md).
  154. Release notes for MartinLoop 0.8.6: [MartinLoop 0.8.6](./docs/release/OSS-0.8.6-RELEASE-NOTES.md).
  155. Release notes for MartinLoop 0.8.7: [MartinLoop 0.8.7](./docs/release/OSS-0.8.7-RELEASE-NOTES.md).
  156. Release notes for MartinLoop 0.8.8: [MartinLoop 0.8.8](./docs/release/OSS-0.8.8-RELEASE-NOTES.md).
  157. Release notes for MartinLoop 0.8.9: [MartinLoop 0.8.9](./docs/release/OSS-0.8.9-RELEASE-NOTES.md).
  158. Release notes for MartinLoop 0.9.0: [MartinLoop 0.9.0](./docs/release/OSS-0.9.0-RELEASE-NOTES.md).
  159. ## Swarm Mode Demo
  160. Run the deterministic 15-agent launch-board demo without provider calls or spend:
  161. ```sh
  162. npx -y martin-loop@0.9.0 demo --swarm
  163. ```
  164. That default result is local simulation evidence only: it is non-governed, is not persisted to the Swarm run store, and does not evaluate signed receipt integrity. Inspect simulation output through the `demo --swarm` human view or `demo --swarm --json`, plus the local files created under `--dir`. Do not use `swarm status`, `swarm inspect`, `swarm dossier`, `swarm verify`, or `swarm share` for the default simulation output.
  165. To exercise the persisted provider-free governance path, use:
  166. ```sh
  167. npx -y martin-loop@0.9.0 demo --swarm --governed --agents 15 --max-concurrency 5 --budget-usd 0
  168. ```
  169. An approved live Codex qualification uses the same persisted route with `--live`, an explicit positive budget, and a clean repository baseline. Persisted modes use `--cwd` and `--runs-dir`; they reject the simulation-only `--dir` and `--force` flags. Live failures exit nonzero and never fall back to simulation.
  170. Persisted demo runs and runs created by `swarm plan` plus `swarm run` are valid inputs to `swarm status`, `swarm inspect`, `swarm dossier`, `swarm verify`, and `swarm share`. A stored run is not automatically verified: rely on the verifier and receipt-integrity result, not the command route alone.
  171. ## Model and Engine Support
  172. MartinLoop governs the job independently of the coding worker.
  173. - Native agent CLIs: Codex, Claude Code, Gemini CLI
  174. - OpenAI-compatible endpoints: Kimi K2, NVIDIA Nemotron, DeepSeek, Qwen/Qwen Coder, Mistral/Codestral, OpenRouter/Together/Fireworks routes, Ollama, LM Studio, llama.cpp, and other compatible endpoints
  175. - Use `--engine openai` for OpenAI-compatible model endpoints.
  176. The worker changes; MartinLoop's budget, scope, verifier, receipt, and integrity contract does not.
  177. More detail: [Model and engine support](./docs/reference/model-support.md)
  178. ## The Run From Start to Handoff
  179. MartinLoop's terminal presentation is built around the governed lifecycle, not around a single verifier command.
  180. **Governed Run Plan** shows the configured finish line before work starts, including the task, budget posture, verifier plan, scope, and execution boundaries.
  181. **Controlled Run** keeps the coding agent working inside those boundaries while MartinLoop tracks attempts, cost, stop conditions, and recovery state.
  182. **Verified Handoff** closes the loop with one authoritative outcome:
  183. - `VERIFIED` when the configured evidence supports the Definition of Done
  184. - `STOPPED` when a configured hard boundary ends the run
  185. - `NEEDS REVIEW` when completion cannot be established from the available evidence
  186. 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.
  187. ## Visual Proof
  188. MartinLoop turns an AI coding run into an inspectable execution record: budget used, verifier result, changed files, rollback evidence, and final receipt.
  189. <div align="center">
  190. <img src="./docs/assets/cli-animated.svg" alt="MartinLoop CLI showing a governed agent run" width="720">
  191. </div>
  192. 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.
  193. <div align="center">
  194. <img src="./docs/assets/side-by-side.svg" alt="MartinLoop governed run compared with an unbounded retry loop" width="720" height="1080">
  195. </div>
  196. ## MartinLoop Arcade
  197. 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.
  198. 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.
  199. Use `--arcade` to offer Arcade immediately for a supported interactive run, or `--no-arcade` to suppress it for that run.
  200. ## Proof Receipts
  201. 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.
  202. This real governed run spent `$0.51` against a `$3.00` budget. The verifier passed and the receipt integrity was signed, but the proof stayed at `EVIDENCE_BOUNDARY` because rollback evidence was not recorded.
  203. <div align="center">
  204. <img src="./docs/assets/proof-receipt-live-governed.png" alt="MartinLoop CLI proof receipt for a governed run with spend, budget, verifier, integrity, and evidence boundary" width="720">
  205. </div>
  206. Generate your own receipt after a governed run:
  207. ```sh
  208. npx -y martin-loop@latest run "Summarize the demo workspace and prove tests still pass" --proof --verify "npm test"
  209. npx -y martin-loop@latest runs verify --latest
  210. npx -y martin-loop@latest share --latest
  211. ```
  212. Example receipt files: [Markdown](./docs/examples/proof-receipts/live-governed-run-receipt.md) and [JSON](./docs/examples/proof-receipts/live-governed-run-receipt.json).
  213. ## Verify the Public Release Yourself
  214. Use this lane from a clean temp directory to verify the public CLI flow exactly as shipped:
  215. ```sh
  216. npx -y martin-loop@0.9.0 enable --engine codex
  217. npx -y martin-loop@0.9.0 --version
  218. npx -y martin-loop@0.9.0 start
  219. npx -y martin-loop@0.9.0 demo
  220. cd martin-loop-demo
  221. npm install
  222. npx -y martin-loop@0.9.0 run "Summarize the demo workspace and prove tests still pass" --verify "npm test" --budget-usd 2 --max-iterations 1 --json
  223. npx -y martin-loop@0.9.0 dossier --latest --json
  224. npx -y martin-loop@0.9.0 share --latest --json
  225. ```
  226. For deterministic installs, pin the package line (`martin-loop@0.9.0`) or use `martin-loop@latest`. Plain `npx martin-loop` can resolve a stale local cache on some machines.
  227. Expected share bundle outputs:
  228. - `share/run-receipt.json`
  229. - `share/run-receipt.md`
  230. - `share/proof-card.svg`
  231. ## See It In Action
  232. 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.
  233. For a deterministic public repro lane, use the benchmark workspace and compare governed execution to unbounded retry behavior:
  234. - `npx martin-loop bench --suite under-3-challenge`
  235. - `npx martin-loop bench --suite ralphy-engineering-50`
  236. ## Ralph-Style Loops
  237. 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.
  238. MartinLoop keeps the useful part of the loop, then adds brakes:
  239. - stop before budget overspend
  240. - classify unsafe or invalid actions before execution
  241. - write an audit record for every attempt
  242. - preserve rollback and verifier evidence for review
  243. - reduce runaway context growth with compact run summaries
  244. ## Failure Taxonomy (13 Runtime Classes)
  245. When a coding agent fails, "something went wrong" is not useful enough.
  246. MartinLoop classifies runtime failures into 13 canonical classes so a failed run can tell you what happened, what needs attention, and what future runs can learn from.
  247. <div align="center">
  248. <img src="./docs/assets/failure-taxonomy-13-classes.png" alt="MartinLoop failure taxonomy showing 13 runtime failure classes and why classification matters" width="900">
  249. </div>
  250. See the canonical table: [Failure Taxonomy (13 Runtime Classes)](./docs/oss/FAILURE-TAXONOMY-13.md).
  251. ## What It Does
  252. - Budget caps stop the next attempt before a configured USD, token, or iteration limit is exceeded.
  253. - Verifier gates require a real check, such as `npm test`, before a run can count as complete.
  254. - Policy checks block unsafe verifier commands, risky path changes, and secret-like task inputs before execution.
  255. - Failure classification uses canonical runtime classes for triage and reporting. See [Failure Taxonomy (13 Runtime Classes)](./docs/oss/FAILURE-TAXONOMY-13.md).
  256. - Run receipts capture stop reason, verifier evidence, budget posture, integrity state, and the next safe action.
  257. - `martin share --latest` turns the latest governed run into a local share bundle with a redacted JSON receipt, Markdown recap, and proof-card SVG.
  258. - MCP integration gives hosts one write-capable execution entrypoint plus richer planning, inspection, and review helpers.
  259. ## How It Works
  260. | Layer | Purpose |
  261. | --- | --- |
  262. | Task contract | Objective, verifier plan, repo root, allowed paths, denied paths, acceptance criteria, workspace, project, and budget. |
  263. | Policy and budget | Defaults come from `martin.config.yaml`; CLI flags can override them. Budget preflight blocks attempts that would exceed policy. |
  264. | Agent adapters | Claude CLI, Codex CLI, Gemini CLI, and direct-provider adapters normalize execution results. |
  265. | Safety and verification | Scope checks, verifier command checks, prompt integrity, and grounding decide whether work can continue. |
  266. | 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. |
  267. ## Trust Boundaries
  268. - Cost and token outputs always include provenance (`actual`, `calculated`, `estimated`, or `unavailable`).
  269. - 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.
  270. - Receipt integrity must be `verified` before a run is treated as trustworthy evidence for external review.
  271. ## CLI
  272. ```text
  273. martin-loop doctor
  274. martin-loop demo
  275. martin-loop session-start [--host <claude|codex|gemini|generic>]
  276. martin-loop phase status|contract|session-start|preflight|run [--execute]
  277. martin-loop preflight <objective> [options]
  278. martin-loop run <objective> [options]
  279. martin-loop bench --suite <suiteId>
  280. martin-loop triage
  281. martin-loop dossier (--latest | --loop-id <id> | --file <path>)
  282. martin-loop runs list|get|attempt|verify ...
  283. martin-loop mcp print-config --host <codex|claude|gemini|cursor|vscode|generic>
  284. martin-loop mcp install --host <codex|claude|gemini|cursor|vscode|generic>
  285. martin-loop mcp verify-install --host <name> [--scope <user|project|local>]
  286. martin-loop mcp rollback --host <name> [--scope <user|project|local>]
  287. martin-loop mcp uninstall --host <name> [--scope <user|project|local>]
  288. martin-loop challenge [--loop-id <id> | --file <path> | --latest]
  289. martin-loop share (--loop-id <id> | --file <path> | --latest) [--out-dir <path>]
  290. martin-loop badge [--format svg|json] [--runs-dir <path>]
  291. ```
  292. <!-- Generated by scripts/generate-install-links.mjs. -->
  293. <!-- MCP package: @martinloop/mcp@0.9.0 -->
  294. [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MartinLoop-007ACC?logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22martin-loop%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40martinloop%2Fmcp%400.9.0%22%5D%7D)
  295. [![Add to Cursor](https://img.shields.io/badge/Cursor-Add_MartinLoop-111111)](cursor://anysphere.cursor-deeplink/mcp/install?name=martin-loop&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBtYXJ0aW5sb29wL21jcEAwLjkuMCJdfQ%3D%3D)
  296. Common options:
  297. ```text
  298. --budget <n> Hard cost cap in USD
  299. --budget-usd <n> Alias for --budget
  300. --soft-limit-usd <n> Soft budget threshold in USD
  301. --verify <cmd> Verifier command after each attempt
  302. --proof Run verifier-only evidence checks without claiming governed execution
  303. --max-iterations <n> Maximum number of attempts
  304. --max-tokens <n> Maximum token budget
  305. --engine <name> Adapter to use: claude, codex, gemini, or openai
  306. --cwd <path> Repo root for the run
  307. --allow-path <glob> Restrict writes to this path pattern; repeatable
  308. --deny-path <glob> Block this path pattern; repeatable
  309. --runs-dir <path> Override the local Martin runs root
  310. ```
  311. Examples below use `npx martin-loop` so they work without a global install. If you install `martin-loop` globally, the `martin` alias works too.
  312. 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.
  313. More detail: [CLI reference](./docs/reference/cli.md) and [configuration reference](./docs/reference/config.md).
  314. <div align="center">
  315. <img src="./docs/assets/cli-static.svg" alt="MartinLoop CLI terminal output" width="720">
  316. </div>
  317. ## Benchmarks
  318. MartinLoop ships a public deterministic benchmark workspace in `benchmarks/` plus the installed-package `bench` command.
  319. From an installed package:
  320. ```sh
  321. npx martin-loop bench --suite under-3-challenge
  322. npx martin-loop bench --suite ralphy-engineering-50
  323. ```
  324. From a clean public clone:
  325. ```sh
  326. pnpm install --frozen-lockfile
  327. pnpm bench:build
  328. pnpm bench:eval
  329. pnpm bench:report:ralphy
  330. ```
  331. Equivalent workspace-filter commands:
  332. ```sh
  333. pnpm --filter @martin/benchmarks build
  334. pnpm --filter @martin/benchmarks test
  335. pnpm --filter @martin/benchmarks eval
  336. pnpm --filter @martin/benchmarks report:ralphy
  337. ```
  338. The installed-package command reads the shipped public fixtures. The repo-clone workflow runs the public benchmark workspace directly.
  339. ## MCP
  340. Run the standalone MCP package directly:
  341. ```sh
  342. npx -y @martinloop/mcp
  343. ```
  344. Add it to common hosts:
  345. ```sh
  346. codex mcp add martin-loop -- npx -y @martinloop/mcp
  347. claude mcp add --transport stdio --scope user martin-loop -- npx -y @martinloop/mcp
  348. claude mcp add --transport stdio --scope user martin-loop -- cmd /c npx -y @martinloop/mcp
  349. ```
  350. Generate host config from the root CLI:
  351. ```sh
  352. npx martin-loop mcp print-config --host codex --transport stdio --profile minimal
  353. npx martin-loop mcp print-config --host claude --transport stdio --profile diagnostic
  354. npx martin-loop mcp print-config --host gemini --transport stdio --profile full-local
  355. npx martin-loop mcp print-config --host generic --transport stdio --profile github-review
  356. ```
  357. The root `martin-loop` package, standalone `@martinloop/mcp` package, plugin metadata, and MCPB product version are aligned at `0.9.0`. The MCPB manifest schema remains `0.3`.
  358. The public MCP release train labels are:
  359. - `0.1.4` operator foundation
  360. - `0.2.0` cockpit expansion
  361. - `0.2.5` public MCP package line
  362. - `0.2.7` usability and review release
  363. - `0.3.0` host adoption and onboarding release
  364. - `0.3.1` review and handoff release
  365. - `0.5.3` execution-control and host-compatibility release
  366. - `0.5.5` governed-autonomous execution and proof-surface release
  367. - `0.5.6` hosted run sync, fail-closed rollback, and verified-completion hardening
  368. The standalone MCP registry/server identifier is `io.github.Keesan12/martin-loop`.
  369. More detail: [MCP setup](./docs/getting-started/mcp.md), [MCP tool reference](./docs/reference/mcp-tools.md), and [MCP compatibility](./docs/reference/mcp-compatibility.md).
  370. ## SDK
  371. ```sh
  372. npm install martin-loop
  373. ```
  374. ```typescript
  375. import { MartinLoop, createClaudeCliAdapter } from "martin-loop";
  376. const loop = new MartinLoop({
  377. adapter: createClaudeCliAdapter({ workingDirectory: process.cwd() }),
  378. defaults: {
  379. workspaceId: "my-workspace",
  380. projectId: "my-project",
  381. budget: {
  382. maxUsd: 3,
  383. softLimitUsd: 2.25,
  384. maxIterations: 3,
  385. maxTokens: 20_000,
  386. },
  387. },
  388. });
  389. const result = await loop.run({
  390. task: {
  391. title: "Fix auth regression",
  392. objective: "Fix the failing auth regression tests",
  393. verificationPlan: ["pnpm test"],
  394. repoRoot: process.cwd(),
  395. },
  396. });
  397. console.log(result.decision.status);
  398. ```
  399. The root SDK also exports `createCodexCliAdapter`, `createGeminiCliAdapter`, `createDirectProviderAdapter`, and `createOpenAiCompatibleAdapter`.
  400. More detail: [SDK reference](./docs/reference/sdk.md) and [package map](./docs/reference/packages.md).
  401. ## Examples
  402. - [Quickstart](./docs/getting-started/quickstart.md)
  403. - [Examples](./docs/getting-started/examples.md)
  404. - [MartinLoop for AI Agents](./docs/for-agents.md)
  405. - [Agent Failure Atlas](./docs/agent-failure-atlas.md)
  406. - [Failure Taxonomy (13 Runtime Classes)](./docs/oss/FAILURE-TAXONOMY-13.md)
  407. - [PRE-028-PUBLIC-SURFACE-DIFF.md](./docs/oss/PRE-028-PUBLIC-SURFACE-DIFF.md)
  408. - [Claude Code walkthrough](./docs/getting-started/claude-code.md)
  409. - [Codex setup](./docs/getting-started/codex.md)
  410. - [MCP setup](./docs/getting-started/mcp.md)
  411. - [MCP tool reference](./docs/reference/mcp-tools.md)
  412. - [Agent run receipts](./docs/oss/AGENT-RUN-RECEIPTS.md)
  413. - [Benchmark + receipt page](./docs/oss/BENCHMARK-RECEIPT-PAGE.md)
  414. - [GitHub Actions budget gate](./examples/github-actions-budget-gate/)
  415. - [OpenCode-style adapter](./examples/opencode-adapter/)
  416. ## Development
  417. Requirements:
  418. - Node.js 20+
  419. - pnpm 10.x
  420. ```sh
  421. git clone https://github.com/Keesan12/martin-loop.git
  422. cd martin-loop
  423. pnpm install --frozen-lockfile
  424. pnpm lint
  425. pnpm test
  426. pnpm build
  427. pnpm public:copy-scan
  428. pnpm public:git-surface
  429. pnpm oss:validate
  430. pnpm public:smoke
  431. pnpm release:matrix:local
  432. ```
  433. Standalone MCP validation:
  434. ```sh
  435. pnpm --filter @martinloop/mcp lint
  436. pnpm --filter @martinloop/mcp test
  437. pnpm --filter @martinloop/mcp build
  438. pnpm --filter @martinloop/mcp smoke:pack
  439. pnpm --filter @martinloop/mcp smoke:published:pack
  440. pnpm --filter @martinloop/mcp verify:release
  441. ```
  442. ## Contributing
  443. Issues, bug reports, workflow feedback, and focused pull requests are welcome. Public-facing docs should stay concise, user-centered, and accurate.
  444. ```sh
  445. git checkout -b feat/your-feature
  446. pnpm lint
  447. pnpm test
  448. git commit -m "feat: describe what you built"
  449. git push -u origin feat/your-feature
  450. ```
  451. <p align="center">
  452. <strong>Star this repo</strong> if you want to give coding agents more real work without babysitting every step.
  453. </p>
  454. <p align="center">
  455. <a href="https://martinloop.com">martinloop.com</a> · <a href="mailto:support@martinloop.com">support@martinloop.com</a>
  456. </p>
  457. <p align="center">
  458. MartinLoop is part of the NVIDIA Inception program.
  459. </p>
  460. <p align="center">
  461. <picture>
  462. <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/nvidia-inception-program.png">
  463. <img src="./docs/assets/nvidia-inception-program-light.png" alt="NVIDIA Inception Program logo" width="280">
  464. </picture>
  465. </p>
  466. ## Telemetry & Privacy
  467. MartinLoop sends minimal anonymous usage data to help improve reliability and prioritize development. On a fresh interactive install, telemetry is enabled by default but remains blocked until the one-time disclosure is shown. After the disclosure, the same run may send the allowlisted anonymous events unless you opt out.
  468. **What is sent:**
  469. - Random installation ID (generated locally, never linked to your identity)
  470. - Per-process session ID
  471. - CLI version, Node version, OS and architecture
  472. - Event name and timestamp
  473. - Command category, run duration, success/failure category
  474. - Whether a receipt was generated; whether recovery occurred
  475. - Opaque remote-experience ID/type after a click
  476. **What is never sent:**
  477. - Source code, prompts, task text, repository contents, file names, file paths
  478. - Environment variables, secrets, provider/model output
  479. - Receipt contents, ledger contents, approval details, verifier evidence
  480. - Email addresses, workspace, project, or organization identifiers
  481. - Raw exception messages or stack traces
  482. **Endpoint:** `https://tupopqvqnyyjuxseyxkr.supabase.co/functions/v1/product-events`
  483. **Headers sent:** `Content-Type: application/json`, `User-Agent: MartinLoop-CLI/<version>`
  484. No authorization header, API key, or direct table access.
  485. **Opt out anytime:**
  486. ```
  487. martin telemetry off
  488. ```
  489. **Inspect what is sent:**
  490. ```
  491. martin telemetry explain
  492. ```
  493. **Environment variables that disable telemetry:** `MARTIN_TELEMETRY_DISABLED=1`, `DO_NOT_TRACK=1`, `CI=1`
  494. Set `MARTIN_TELEMETRY_DEBUG=1` to print the telemetry envelope to stderr without transmitting it.
  495. MartinLoop continues to work normally with telemetry disabled. No features are gated on telemetry consent.
  496. ## License
  497. Apache-2.0. See [LICENSE](./LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.