martin-loop 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +362 -344
  3. package/dist/bin/martin-loop.js +23 -0
  4. package/dist/index.d.ts +22 -0
  5. package/dist/index.js +31 -0
  6. package/dist/vendor/adapters/claude-cli.d.ts +89 -0
  7. package/dist/vendor/adapters/claude-cli.js +555 -0
  8. package/dist/vendor/adapters/cli-bridge.d.ts +28 -0
  9. package/dist/vendor/adapters/cli-bridge.js +127 -0
  10. package/dist/vendor/adapters/direct-provider.d.ts +10 -0
  11. package/dist/vendor/adapters/direct-provider.js +41 -0
  12. package/dist/vendor/adapters/index.d.ts +5 -0
  13. package/dist/vendor/adapters/index.js +5 -0
  14. package/dist/vendor/adapters/runtime-support.d.ts +14 -0
  15. package/dist/vendor/adapters/runtime-support.js +52 -0
  16. package/dist/vendor/adapters/stub-agent-cli.d.ts +8 -0
  17. package/dist/vendor/adapters/stub-agent-cli.js +41 -0
  18. package/dist/vendor/adapters/stub-direct-provider.d.ts +8 -0
  19. package/dist/vendor/adapters/stub-direct-provider.js +10 -0
  20. package/dist/vendor/cli/bin/martin.d.ts +2 -0
  21. package/dist/vendor/cli/bin/martin.js +19 -0
  22. package/dist/vendor/cli/index.d.ts +39 -0
  23. package/dist/vendor/cli/index.js +634 -0
  24. package/dist/vendor/cli/persistence.d.ts +34 -0
  25. package/dist/vendor/cli/persistence.js +71 -0
  26. package/dist/vendor/contracts/governance.d.ts +21 -0
  27. package/dist/vendor/contracts/governance.js +12 -0
  28. package/dist/vendor/contracts/index.d.ts +330 -0
  29. package/dist/vendor/contracts/index.js +203 -0
  30. package/dist/vendor/core/compiler.d.ts +50 -0
  31. package/dist/vendor/core/compiler.js +47 -0
  32. package/dist/vendor/core/grounding.d.ts +37 -0
  33. package/dist/vendor/core/grounding.js +270 -0
  34. package/dist/vendor/core/index.d.ts +145 -0
  35. package/dist/vendor/core/index.js +1099 -0
  36. package/dist/vendor/core/leash.d.ts +48 -0
  37. package/dist/vendor/core/leash.js +408 -0
  38. package/dist/vendor/core/persistence/compiler.d.ts +18 -0
  39. package/dist/vendor/core/persistence/compiler.js +35 -0
  40. package/dist/vendor/core/persistence/index.d.ts +6 -0
  41. package/dist/vendor/core/persistence/index.js +4 -0
  42. package/dist/vendor/core/persistence/ledger.d.ts +23 -0
  43. package/dist/vendor/core/persistence/ledger.js +10 -0
  44. package/dist/vendor/core/persistence/store.d.ts +77 -0
  45. package/dist/vendor/core/persistence/store.js +84 -0
  46. package/dist/vendor/core/policy.d.ts +126 -0
  47. package/dist/vendor/core/policy.js +625 -0
  48. package/dist/vendor/core/rollback.d.ts +11 -0
  49. package/dist/vendor/core/rollback.js +219 -0
  50. package/docs/oss/EXAMPLES.md +126 -126
  51. package/docs/oss/OSS-BOUNDARY-REPORT.json +113 -113
  52. package/docs/oss/OSS-BOUNDARY-REPORT.md +48 -48
  53. package/docs/oss/QUICKSTART.md +135 -135
  54. package/docs/oss/README.md +93 -93
  55. package/docs/oss/RELEASE-SURFACE-REPORT.json +45 -45
  56. package/docs/oss/RELEASE-SURFACE-REPORT.md +35 -35
  57. package/package.json +56 -54
package/README.md CHANGED
@@ -1,344 +1,362 @@
1
- <div align="center">
2
-
3
- <!-- <img src="docs/assets/martinloop_logo_1.png" alt="MartinLoop" width="200"> -->
4
-
5
- # MartinLoop
6
-
7
- ### The agentic AI governance runtime. Hard enforcement, not suggestions.
8
-
9
- [![License: MIT](https://img.shields.io/badge/license-MIT-7c3aed?style=flat-square)](./LICENSE)
10
- [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square&logo=typescript&logoColor=white)](./tsconfig.json)
11
- [![Node](https://img.shields.io/badge/node-%3E%3D20-3c873a?style=flat-square&logo=nodedotjs&logoColor=white)](#quick-start)
12
- [![npm](https://img.shields.io/badge/npm-martin--loop-cc3534?style=flat-square&logo=npm&logoColor=white)](https://npmjs.com/package/martin-loop)
13
-
14
- <br>
15
-
16
- > **Your overnight AI pipeline estimated $2.40.**
17
- > **You woke up to $165.**
18
- >
19
- > 47 retries. No hard stop. No rollback. No audit trail. Nothing merged.
20
- > **MartinLoop exists so that never happens again.**
21
-
22
- </div>
23
-
24
- ---
25
-
26
- ## ⚡ Quick Start
27
-
28
- ## Release Surface
29
-
30
- The frozen public package surface for this RC is:
31
-
32
- ```sh
33
- npm install martin-loop
34
- npx martin-loop
35
- ```
36
-
37
- ```typescript
38
- import { MartinLoop } from "martin-loop"
39
- ```
40
-
41
- Phase 13 RC gate commands:
42
-
43
- ```sh
44
- pnpm oss:validate
45
- pnpm public:smoke
46
- pnpm repo:smoke
47
- pnpm rc:validate
48
- pnpm pilot:prep:validate
49
- pnpm release:matrix:local
50
- ```
51
-
52
- Registry publication is intentionally held for a later release step; this repository can validate the package surface locally before publishing.
53
-
54
- ---
55
-
56
- ### 1. Install
57
-
58
- ```sh
59
- npm install -g martin-loop
60
- ```
61
-
62
- This gives you two commands: `martin` and `martin-loop` (both identical).
63
-
64
- ### 2. Run a governed task
65
-
66
- ```sh
67
- martin run "fix the auth regression" \
68
- --budget 3.00 \
69
- --verify "pnpm test"
70
- ```
71
-
72
- What each flag does:
73
- - `--budget 3.00` hard kill at $3.00. The subprocess is terminated at the limit.
74
- - `--verify "pnpm test"` — shell command run after each attempt. Loop only exits success when it passes.
75
-
76
- The first argument after `run` is your objective. You can also use `--objective`:
77
-
78
- ```sh
79
- martin run --objective "fix the auth regression" --budget 3.00 --verify "pnpm test"
80
- ```
81
-
82
- ### 3. Resume an interrupted run
83
-
84
- ```sh
85
- martin resume <loopId>
86
- ```
87
-
88
- Loads the persisted loop record from `~/.martin/runs/` by ID.
89
-
90
- ### 4. Inspect a run file
91
-
92
- ```sh
93
- martin inspect --file ~/.martin/runs/<workspaceId>.jsonl
94
- ```
95
-
96
- Prints a portfolio summary (total cost, attempts, outcomes) for all loops in the file.
97
-
98
- ---
99
-
100
- ## 🖥️ All CLI Flags
101
-
102
- ```
103
- martin run <objective> [options]
104
-
105
- --objective <text> The task to accomplish (or pass as first positional arg)
106
- --budget <n> Hard cost cap in USD (subprocess killed at limit)
107
- --budget-usd <n> Alias for --budget
108
- --verify <cmd> Shell command used as the verifier after each attempt
109
- --max-iterations <n> Maximum number of attempts (default: 3)
110
- --engine <name> Adapter to use: claude (default) or codex
111
- --model <name> Override the model (e.g. claude-sonnet-4-6)
112
- --cwd <path> Repo root for the run (default: current directory)
113
- --allow-path <glob> Restrict agent to this path pattern (repeatable)
114
- --deny-path <glob> Block agent from this path pattern (repeatable)
115
- --accept <criterion> Add an acceptance criterion injected into the prompt (repeatable)
116
- --config <path> Path to a martin.config.yaml policy file
117
- --workspace <id> Workspace ID for the run record (default: ws_default)
118
- --project <id> Project ID for the run record (default: proj_default)
119
- --metadata <key=value> Attach metadata to the run record (repeatable)
120
- ```
121
-
122
- ---
123
-
124
- ## 📋 Policy File (martin.config.yaml)
125
-
126
- Drop a `martin.config.yaml` in your repo root to set governance defaults:
127
-
128
- ```yaml
129
- budget:
130
- maxUsd: 5.00
131
- softLimitUsd: 3.75
132
- maxIterations: 5
133
- maxTokens: 40000
134
-
135
- governance:
136
- destructiveActionPolicy: approval
137
- telemetryDestination: local-only
138
- verifierRules:
139
- - pnpm test
140
- ```
141
-
142
- The CLI picks this up automatically. CLI flags always override the config file.
143
-
144
- ---
145
-
146
- ## 📦 TypeScript SDK
147
-
148
- Install as a library:
149
-
150
- ```sh
151
- npm install martin-loop
152
- ```
153
-
154
- ```typescript
155
- import {
156
- MartinLoop,
157
- createClaudeCliAdapter,
158
- createCodexCliAdapter
159
- } from 'martin-loop'
160
-
161
- const loop = new MartinLoop({
162
- adapter: createClaudeCliAdapter({ workingDirectory: process.cwd() }),
163
- defaults: {
164
- budget: {
165
- maxUsd: 3.00,
166
- softLimitUsd: 2.25,
167
- maxIterations: 3,
168
- maxTokens: 20_000
169
- }
170
- }
171
- })
172
-
173
- const result = await loop.run({
174
- workspaceId: 'my-workspace',
175
- projectId: 'my-project',
176
- task: {
177
- title: 'Fix auth regression',
178
- objective: 'Fix the failing auth regression tests',
179
- verificationPlan: ['pnpm test'],
180
- repoRoot: process.cwd()
181
- },
182
- budget: {
183
- maxUsd: 3.00,
184
- softLimitUsd: 2.25,
185
- maxIterations: 3,
186
- maxTokens: 20_000
187
- }
188
- })
189
-
190
- // result.decision.status → 'completed' | 'exited' | 'failed'
191
- // result.decision.lifecycleState 'completed' | 'budget_exit' | 'human_escalation' | ...
192
- // result.loop.cost.actualUsd → actual USD spent
193
- // result.loop.attempts.length → number of attempts made
194
- // result.decision.reason → why the loop exited
195
- ```
196
-
197
- ### Using Codex instead of Claude
198
-
199
- ```typescript
200
- const loop = new MartinLoop({
201
- adapter: createCodexCliAdapter({ workingDirectory: process.cwd() })
202
- })
203
- ```
204
-
205
- ### Using the lower-level `runMartin` directly
206
-
207
- ```typescript
208
- import { runMartin, createClaudeCliAdapter } from 'martin-loop'
209
-
210
- const result = await runMartin({
211
- workspaceId: 'ws_default',
212
- projectId: 'proj_default',
213
- task: {
214
- title: 'Fix auth regression',
215
- objective: 'Fix the failing auth regression tests',
216
- verificationPlan: ['pnpm test'],
217
- repoRoot: process.cwd()
218
- },
219
- budget: {
220
- maxUsd: 3.00,
221
- softLimitUsd: 2.25,
222
- maxIterations: 3,
223
- maxTokens: 20_000
224
- },
225
- adapter: createClaudeCliAdapter({ workingDirectory: process.cwd() })
226
- })
227
- ```
228
-
229
- ---
230
-
231
- ## 🧠 Architecture
232
-
233
- Five governance layers from policy to runtime enforcement.
234
-
235
- ```
236
- ┌──────────────────────────────────────────────────────────┐
237
- MartinLoop Governance Stack │
238
- ├──────────────────────┬───────────────────────────────────┤
239
- Autonomy Envelope │ Surface · Path · Command │
240
- (policy-enforced) │ Leash — pre-execution gate │
241
- ├──────────────────────┼───────────────────────────────────┤
242
- │ Model Router │ Cost-aware adapter selection │
243
- │ │ Fallback chain + model override │
244
- ├──────────────────────┼───────────────────────────────────┤
245
- Agent Adapters │ Claude Code · Codex · any CLI │
246
- │ │ Direct + stub adapters │
247
- ├──────────────────────┼───────────────────────────────────┤
248
- │ Safety Leash │ Pre-execution verification gate │
249
- │ │ Filesystem + secret + command │
250
- ├──────────────────────┼───────────────────────────────────┤
251
- │ Persistence │ Per-run JSONL in ~/.martin/runs/ │
252
- │ │ Portfolio inspect + resume │
253
- └──────────────────────┴───────────────────────────────────┘
254
- ```
255
-
256
- ---
257
-
258
- ## 🛡️ What MartinLoop Enforces Today
259
-
260
- **1. Hard budget cap.**
261
- Every run has a `maxUsd` limit. When the cost reaches that limit the subprocess is terminated — not warned.
262
-
263
- **2. Iteration cap.**
264
- Every run has a `maxIterations` limit. The loop exits when it is hit, regardless of progress.
265
-
266
- **3. Filesystem leash.**
267
- If `allowedPaths` or `deniedPaths` are configured, any attempt that writes outside the envelope is blocked and rolled back before the patch is kept.
268
-
269
- **4. Secret leash.**
270
- Values that look like secrets (API keys, tokens) in the task objective or acceptance criteria are blocked before any attempt runs.
271
-
272
- **5. Verifier gate.**
273
- The loop only marks a run successful if the verifier command exits `0`. A passing verifier is required for a `completed` lifecycle state.
274
-
275
- **6. Rollback on failure.**
276
- When an attempt is discarded (failed verifier, safety violation, patch decision), MartinLoop restores the filesystem to the pre-attempt state using a git-backed snapshot.
277
-
278
- **7. Run persistence.**
279
- Every run is written to `~/.martin/runs/<workspaceId>.jsonl`. Use `martin resume` and `martin inspect` to read it back.
280
-
281
- ---
282
-
283
- ## 📦 OSS Packages
284
-
285
- | Package | What It Does |
286
- |---------|-------------|
287
- | `martin-loop` | Self-contained facade everything below, vendored and published |
288
- | `@martin/core` | Runtime controller, leash, router, rollback, policy engine |
289
- | `@martin/cli` | `martin run` · `inspect` · `resume` CLI commands |
290
- | `@martin/adapters` | Claude Code, Codex CLI, direct-provider, stub adapters |
291
- | `@martin/contracts` | Shared types: loop, policy, leash, budget, rollback |
292
-
293
- All `@martin/*` packages are workspace-internal. Install `martin-loop` from npm it bundles them all.
294
-
295
- ---
296
-
297
- ## 🔧 Development
298
-
299
- **Requirements:** Node 20+ · pnpm 8+
300
-
301
- ```sh
302
- # Clone and install
303
- git clone https://github.com/Keesan12/MartinLoop
304
- cd martin-loop && pnpm install
305
-
306
- # Full test suite
307
- pnpm test
308
-
309
- # Type check all packages
310
- pnpm -r lint
311
-
312
- # Build all packages + public facade
313
- pnpm build
314
-
315
- # Publish (after build)
316
- npm publish
317
- ```
318
-
319
- ---
320
-
321
- ## 🤝 Contributing
322
-
323
- ```sh
324
- git checkout -b feat/your-feature
325
-
326
- # Make changes, then:
327
- pnpm -r lint && pnpm test # must stay green
328
-
329
- git commit -m "feat: describe what you built"
330
- git push -u origin feat/your-feature
331
- # Open a PR against main
332
- ```
333
-
334
- Conventional commits: `feat:` · `fix:` · `chore:` · `docs:` · `refactor:` · `test:`
335
-
336
- ---
337
-
338
- <div align="center">
339
-
340
- **MIT Licensed** · [martinloop.com](https://martinloop.com) · [keesan@martinloop.com](mailto:keesan@martinloop.com)
341
-
342
- *"AI coding accountability: completes good work · refuses bad work · stops uneconomical work."*
343
-
344
- </div>
1
+ <div align="center">
2
+
3
+ <img src="./docs/assets/martinloop-logo.png" alt="MartinLoop" width="260">
4
+
5
+ ### A governed runtime for autonomous AI coding agents. ⭐⭐⭐
6
+
7
+ [![License: MIT](https://img.shields.io/badge/license-MIT-7c3aed?style=flat-square)](./LICENSE)
8
+ [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square&logo=typescript&logoColor=white)](./tsconfig.base.json)
9
+ [![Node](https://img.shields.io/badge/node-%3E%3D20-3c873a?style=flat-square&logo=nodedotjs&logoColor=white)](#quick-start)
10
+ [![npm](https://img.shields.io/badge/npm-martin--loop-cc3534?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/martin-loop)
11
+
12
+ <br>
13
+
14
+ **Your overnight AI pipeline estimated $2.40.**
15
+ **You woke up to a $65 bill.**
16
+ <br> 47 retries. No hard stop. No rollback. No audit trail. Nothing merged.
17
+ MartinLoop exists so that never happens again.✅ <br> <br>
18
+ If you think autonomous AI coding agents need budgets, brakes, and receipts, ⭐ the repo so more builders can find it.
19
+ <br>
20
+
21
+ > AI coding agents are useful. Unbounded retry loops are not.
22
+ >
23
+ > MartinLoop wraps agent runs with budgets, policy checks, verifier gates, rollback evidence, and inspectable run records.
24
+ <br>
25
+ <img src="./docs/assets/cli-animated.svg" alt="MartinLoop CLI — governed agent run" width="720">
26
+
27
+ </div>
28
+
29
+ ---
30
+
31
+ ## The Problem
32
+
33
+ A typical autonomous coding loop keeps attempting work until tests pass. Without a governance layer, that loop can keep spending, mutate files outside the intended scope, lose track of why it failed, and leave teams without a clean audit trail.
34
+
35
+ Ralph-style loops are powerful but they attempt ➡️ check ➡️ retry ➡️ repeat, with no strong answer to:
36
+
37
+ - What changed?
38
+ - What did it cost?
39
+ - Why was it allowed?
40
+ - Why did it stop?
41
+ - Can we inspect or resume it later?
42
+
43
+ MartinLoop governs the failure mode.
44
+
45
+ ---
46
+
47
+ ## The Solution
48
+
49
+ Martin Loop wraps AI coding loops with a governance layer.
50
+
51
+ It does not try to replace the agent pattern. It makes that pattern safe to run.
52
+
53
+ ### What MartinLoop Does Today
54
+
55
+ | Capability | Current behavior |
56
+ |---|---|
57
+ | Budget governance | Enforces `maxUsd`, `softLimitUsd`, `maxIterations`, and `maxTokens`; rejects attempts projected to exceed remaining budget and exits on budget or iteration exhaustion. Hard USD budget caps that stop work before the next attempt breaches policy. |
58
+ | Verifier gate | A run only reaches `completed` when the adapter result and verifier state pass. Unsafe verifier commands are blocked before agent execution. |
59
+ | Failure taxonomy | Classifies failures across 11 current classes, including hallucination, test regression, scope creep, repo grounding failure, environment mismatch, and budget pressure, that distinguishes real success from unsafe, invalid, or terminal behavior.|
60
+ | Safety leash | Evaluates verifier commands, file scope, dependency or migration changes that require approval, and secret-like values in task text. **Policy-as-code**. |
61
+ | Rollback evidence | Captures rollback boundaries and restore outcomes for repo-backed attempts when a persistence store is configured. |
62
+ | Context distillation | Carries a distilled summary of recent attempts and remaining constraints into subsequent attempts. |
63
+ | Run records | The CLI appends JSONL loop records under `~/.martin/runs/<workspaceId>.jsonl`; lower-level stores can also persist contracts, ledgers, and attempt artifacts.
64
+
65
+
66
+ ⭐The result is a runtime that can complete good work, refuse unsafe work, stop uneconomical work, and leave evidence behind.✅
67
+ ---
68
+
69
+ ## The Ralph Loop, explained
70
+
71
+ **"Everybody has gotten infatuated with what we call these Ralph Wiggum loops, just like send the thing off and it'll just go figure something out..A, It never figures anything out. And B, you just get this ginormous bill...**" - Chamath Palihapitiya, All-In Podcast #263, March 2026
72
+
73
+ The **Ralph Loop** is the failure mode where an AI coding agent keeps trying without knowing when it should stop.
74
+
75
+ The pattern is simple: attempt the task, run checks, retry on failure, repeat. The problem is not that the loop exists. The problem is that most implementations have no hard budget cap, no signed evidence layer, and no pre-execution control system. They know how to keep trying. They do **not** know when continuing is unsafe, uneconomical, or impossible.
76
+
77
+ ✅ Martin Loop solves the Ralph Loop problem by enforcing rules **before** damage happens:
78
+
79
+ - it stops the next attempt before budget overspend
80
+ - it classifies unsafe or invalid actions before execution
81
+ - it appends a structured JSONL audit record for every attempt
82
+ - it rolls back failed runs instead of leaving broken state behind
83
+ - it reduces runaway token growth with context distillation
84
+
85
+ If Ralph ever burned $165.70 on your dime, you're in the right place. Martin stopped him at $4.97 with a full audit trail. LFG! 🚀 Finally a Martin Prince leash for Ralph Wiggums! :)
86
+
87
+ <div align="center">
88
+ <img src="./docs/assets/martin-raplph.png.jpg" alt="Martin vs Ralph governed vs ungoverned agent loop" width="240">
89
+ </div>
90
+
91
+ ### How It Works — Five Layers
92
+
93
+ | Layer | What it does |
94
+ |---|---|
95
+ | **1. Task Contract** | Objective, verifier plan, repo root, allowed/denied paths, acceptance criteria, workspace, project, and budget. |
96
+ | **2. Policy & Budget** | Defaults from `martin.config.yaml`; CLI flags override. Budget preflight rejects attempts before execution. |
97
+ | **3. Agent Adapters** | Claude CLI, Codex CLI, direct-provider, and stub adapters normalize execution results into the core runtime contract. |
98
+ | **4. Safety & Verification** | Verifier commands, file scope, approval-boundary changes, secret-like values, and grounding determine whether work is kept. |
99
+ | **5. Persistence** | CLI writes JSONL records under `~/.martin/runs/`. Repo-backed runs can also persist contracts, ledgers, diffs, and rollback artifacts. |
100
+
101
+ ---
102
+
103
+ ## See It In Action
104
+
105
+ Same task, same starting state. MartinLoop completes in one verified attempt at `$2.30`. The uncontrolled loop retries four times, spends `$5.20`, and fails with no audit trail.
106
+
107
+ Martin Loop matters because it turns AI coding from an opaque experiment into something that can be governed, replayed, verified, and trusted.
108
+
109
+ <div align="center">
110
+ <img src="./docs/assets/side-by-side.svg" alt="Martin vs Ralph governed vs ungoverned agent loop side-by-side benchmark comparison" width="720" height="1080">
111
+ </div>
112
+
113
+
114
+ Reproducible locally:
115
+
116
+ ```sh
117
+ pnpm --filter @martin/benchmarks test
118
+ pnpm --filter @martin/benchmarks eval
119
+ pnpm --filter @martin/benchmarks eval:phase12
120
+ ```
121
+
122
+ ---
123
+
124
+ ## Quick Start
125
+
126
+ ```sh
127
+ npm install -g martin-loop
128
+ ```
129
+
130
+ This installs both the `martin-loop` package and the `martin` command alias. The package is currently published on npm as version `0.1.2`.
131
+
132
+ ### Public Package Surface
133
+
134
+ The frozen public package surface for this release candidate is:
135
+
136
+ - Install target: `npm install martin-loop`
137
+ - CLI target: `npx martin-loop`
138
+ - SDK target: `import { MartinLoop } from "martin-loop"`
139
+
140
+ The `martin` command alias is installed for local operator convenience, but the public CLI surface is `npx martin-loop`.
141
+
142
+ ### Run a governed task
143
+
144
+ ```sh
145
+ martin run "fix the auth regression" \
146
+ --budget 3.00 \
147
+ --verify "pnpm test"
148
+ ```
149
+
150
+ You can also pass the objective explicitly:
151
+
152
+ ```sh
153
+ martin run --objective "fix the auth regression" --budget 3.00 --verify "pnpm test"
154
+ ```
155
+
156
+ For a no-spend repo-local dry run, use the stub adapter:
157
+
158
+ ```powershell
159
+ $env:MARTIN_LIVE='false'
160
+ pnpm run:cli -- run --objective "Summarize the current runtime state" --verify "pnpm --filter @martin/core test"
161
+ Remove-Item Env:MARTIN_LIVE
162
+ ```
163
+
164
+ ### Inspect or resume runs
165
+
166
+ ```sh
167
+ martin inspect --file ~/.martin/runs/<workspaceId>.jsonl
168
+ martin resume <loopId>
169
+ ```
170
+
171
+ `inspect` prints a portfolio summary for records in the file. `resume` looks up a persisted loop record by ID under `~/.martin/runs/`.
172
+
173
+ ---
174
+
175
+ ## CLI
176
+
177
+ ```text
178
+ martin run <objective> [options]
179
+
180
+ --objective <text> The task to accomplish, or pass it as the first positional arg
181
+ --budget <n> Hard cost cap in USD
182
+ --budget-usd <n> Alias for --budget
183
+ --soft-limit-usd <n> Soft budget threshold in USD
184
+ --verify <cmd> Verifier command after each attempt
185
+ --max-iterations <n> Maximum number of attempts
186
+ --max-tokens <n> Maximum total token budget
187
+ --engine <name> Adapter to use: claude (default) or codex
188
+ --model <name> Override the adapter model
189
+ --cwd <path> Repo root for the run
190
+ --allow-path <glob> Restrict agent writes to this path pattern; repeatable
191
+ --deny-path <glob> Block this path pattern; repeatable
192
+ --accept <criterion> Add an acceptance criterion; repeatable
193
+ --config <path> Path to a martin.config.yaml file
194
+ --workspace <id> Workspace ID for the run record
195
+ --project <id> Project ID for the run record
196
+ --metadata <key=value> Attach metadata to the run record; repeatable
197
+ ```
198
+
199
+ The public CLI also includes `inspect`, `resume`, and a `bench` redirect that points reviewers to the workspace benchmark harness.
200
+
201
+ <div align="center">
202
+ <img src="./docs/assets/cli-static.svg" alt="MartinLoop CLI terminal output" width="720">
203
+ </div>
204
+
205
+ ---
206
+
207
+ ## Policy File
208
+
209
+ Drop a `martin.config.yaml` in your repo root to set governance defaults:
210
+
211
+ ```yaml
212
+ budget:
213
+ maxUsd: 5.00
214
+ softLimitUsd: 3.75
215
+ maxIterations: 5
216
+ maxTokens: 40000
217
+
218
+ governance:
219
+ destructiveActionPolicy: approval
220
+ telemetryDestination: local-only
221
+ verifierRules:
222
+ - pnpm test
223
+ ```
224
+
225
+ CLI flags override config values when provided.
226
+
227
+ ---
228
+
229
+ ## TypeScript SDK
230
+
231
+ ```sh
232
+ npm install martin-loop
233
+ ```
234
+
235
+ ```typescript
236
+ import {
237
+ MartinLoop,
238
+ createClaudeCliAdapter,
239
+ createCodexCliAdapter,
240
+ runMartin
241
+ } from "martin-loop";
242
+
243
+ const loop = new MartinLoop({
244
+ adapter: createClaudeCliAdapter({ workingDirectory: process.cwd() }),
245
+ defaults: {
246
+ workspaceId: "my-workspace",
247
+ projectId: "my-project",
248
+ budget: {
249
+ maxUsd: 3.00,
250
+ softLimitUsd: 2.25,
251
+ maxIterations: 3,
252
+ maxTokens: 20_000
253
+ }
254
+ }
255
+ });
256
+
257
+ const result = await loop.run({
258
+ task: {
259
+ title: "Fix auth regression",
260
+ objective: "Fix the failing auth regression tests",
261
+ verificationPlan: ["pnpm test"],
262
+ repoRoot: process.cwd()
263
+ }
264
+ });
265
+
266
+ console.log(result.decision.status);
267
+ ```
268
+
269
+ Use Codex instead of Claude by swapping adapters:
270
+
271
+ ```typescript
272
+ const loop = new MartinLoop({
273
+ adapter: createCodexCliAdapter({ workingDirectory: process.cwd() })
274
+ });
275
+ ```
276
+
277
+ The lower-level `runMartin` function is also exported for callers that want to assemble the runtime input directly.
278
+
279
+ ---
280
+
281
+ ## Workspace Map
282
+
283
+ | Package or app | Role |
284
+ |---|---|
285
+ | `martin-loop` | Root public npm facade that vendors the runtime, CLI, adapters, and contracts into `dist/`. |
286
+ | `@martin/contracts` | Shared types for loops, policy, governance, budget, telemetry, and rollback. |
287
+ | `@martin/core` | Runtime controller, policy engine, safety leash, grounding, persistence, and rollback logic. |
288
+ | `@martin/adapters` | Claude CLI, Codex CLI, direct-provider, and stub adapter surfaces. |
289
+ | `@martin/cli` | Local CLI implementation for `run`, `inspect`, `resume`, and the benchmark redirect. |
290
+ | `@martin/mcp` | MCP server tools: `martin_run`, `martin_inspect`, and `martin_status`. |
291
+ | `benchmarks/` | Workspace-only deterministic benchmark and RC validation harness. |
292
+ | `apps/control-plane/` | Hosted control-plane workstream, outside the initial npm package surface. |
293
+ | `apps/local-dashboard/` | Local dashboard/read-model viewer, not currently packaged as public npm API. |
294
+
295
+ The `@martin/core`, `@martin/adapters`, and `@martin/contracts` package manifests are still private workspace packages; the public install target is the root `martin-loop` facade.
296
+
297
+ ---
298
+
299
+ ## Development
300
+
301
+ Requirements: Node 20+ and pnpm 10.x.
302
+
303
+ ```sh
304
+ git clone https://github.com/Keesan12/martin-loop.git
305
+ cd martin-loop
306
+ pnpm install
307
+
308
+ pnpm test
309
+ pnpm lint
310
+ pnpm build
311
+ ```
312
+
313
+ ```md
314
+ Current RC gate commands:
315
+
316
+ ```sh
317
+ pnpm oss:validate
318
+ pnpm public:smoke
319
+ pnpm repo:smoke
320
+ pnpm rc:validate
321
+ pnpm pilot:prep:validate
322
+ pnpm release:matrix:local
323
+ Caution: Registry Publication
324
+
325
+ This package is published through the public martin-loop package surface. Treat registry publication as a guarded release step: verify the RC gate commands, confirm the version follows semantic versioning, and document breaking changes before publishing.
326
+
327
+ > **Caution:** This package is live on npm. Treat registry publication as a guarded release step — verify the RC gate commands, confirm semantic versioning, and document breaking changes before publishing.
328
+
329
+ The repository is organized as a dual-track workspace: the OSS runtime and package facade are present and published, while the hosted control-plane, local dashboard, and benchmark harness remain gated in private workspace for future release rather than the primary npm package API.
330
+
331
+ Helpful docs:
332
+
333
+ - [OSS quickstart](./docs/oss/QUICKSTART.md)
334
+ - [OSS examples](./docs/oss/EXAMPLES.md)
335
+ - [OSS boundary report](./docs/oss/OSS-BOUNDARY-REPORT.md)
336
+ - [Release surface report](./docs/oss/RELEASE-SURFACE-REPORT.md)
337
+
338
+ ---
339
+
340
+ ## Contributing
341
+
342
+ ```sh
343
+ git checkout -b feat/your-feature
344
+ pnpm lint
345
+ pnpm test
346
+ git commit -m "feat: describe what you built"
347
+ git push -u origin feat/your-feature
348
+ ```
349
+
350
+ Conventional commit prefixes: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, and `test:`.
351
+
352
+ ---
353
+
354
+ <div align="center">
355
+
356
+ **⭐Give the repo a star⭐** if you think AI coding needs budgets, brakes, and receipts.
357
+
358
+ **MIT Licensed** · [martinloop.com](https://martinloop.com) · [keesan@martinloop.com](mailto:keesan@martinloop.com)
359
+
360
+ *"AI coding accountability: completes good work, refuses unsafe work, stops uneconomical work."*
361
+
362
+ </div>