Skip to content

quickstart.md

Latest commit

 

History

History
115 lines (81 loc) · 3.73 KB

quickstart.md

File metadata and controls

115 lines (81 loc) · 3.73 KB
Raw

Quickstart

Use this guide to get one governed MartinLoop run and one evidence review in a few minutes.

Prerequisites

  • Node.js 20+
  • npm for the packaged demo
  • pnpm 10.x if you are working from this repository
  • optional for live runs: Claude Code or Codex CLI installed and authenticated

Recommended First Run

npx -y martin-loop@latest start
npx -y martin-loop@latest demo
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

This path proves the run/dossier loop with a real spend-governed execution. run auto-checks doctor, session-start, and preflight, then executes when the environment is ready.

Install the CLI

npm install -g martin-loop
npx -y martin-loop@latest doctor

doctor checks whether MartinLoop can find the local tools, agents, and run directories it needs.

For deterministic package-line verification in fresh environments:

npx -y martin-loop@0.3.2 --version
npm view martin-loop version
npm view @martinloop/mcp version

If npx martin-loop --version differs from npm live, run npx -y martin-loop@latest --version or pin @0.3.2 to avoid local cache drift.

Run a Governed Task

npx -y martin-loop@latest preflight "fix the auth regression" --verify "pnpm test"
npx -y martin-loop@latest run "fix the auth regression" --budget 3.00 --verify "pnpm test"

By default, MartinLoop auto-checks doctor, session-start, and preflight for the same repo and task before a real run will spend money. If preflight finds a real blocker, MartinLoop stops before live spend and tells you what to fix.

For explicit no-spend validation, pass --proof intentionally:

npx -y martin-loop@latest run "fix the auth regression" --proof --budget 1.00 --verify "pnpm test"

If you want to inspect the governed checks first:

npx -y martin-loop@latest doctor
npx -y martin-loop@latest session-start
npx -y martin-loop@latest preflight "fix the auth regression" --verify "pnpm test"

Review Evidence

npx -y martin-loop@latest triage
npx -y martin-loop@latest dossier --latest
npx -y martin-loop@latest share --latest

Use triage to rank saved runs by urgency. Use dossier when you want one run receipt: stop reason, verifier evidence, budget status, rollback or artifact evidence, and the next safe action. Use share when you want a redacted bundle you can attach to a ticket, send to a teammate, or keep with the run directory.

The share bundle contains run-receipt.json, run-receipt.md, and proof-card.svg.

To print exact artifact paths from your latest run:

npx -y martin-loop@latest share --latest --json

Optional Hosted Dashboard Sync

Governed work and its receipt are local-first. Dashboard sync is optional and can happen after the run without another provider call.

Provide both values through your shell or secret manager; never paste a real token into source files, documentation, or logs:

MARTIN_API_TOKEN=<workspace-token>
MARTIN_TELEMETRY_ENDPOINT=https://<your-hosted-endpoint>
martin sync status
martin sync flush

If either value is missing, martin sync flush exits nonzero and leaves the queued evidence intact. After configuration is available, a later flush uploads the same run ID. Missing hosted configuration does not invalidate the local governed run, verifier evidence, or receipt.

Repository Development

pnpm install --frozen-lockfile
pnpm lint
pnpm test
pnpm build

More detail: