Marvin is an autonomous coding loop that reads a plan file, then iteratively delegates implementation and review subagents until every task is done — or it gives up in despair. Named after the Paranoid Android from The Hitchhiker's Guide to the Galaxy, it approaches your codebase with vast intelligence and infinite sorrow.

Marvin runs in a loop, on top of either Claude Code or Opencode harnesses. Each iteration:

1. Orient — reads the plan file and checks for leftover changes from interrupted runs
2. Select — picks the highest-priority incomplete task
3. Build — delegates implementation to a build agent (never writes code itself)
4. Review — delegates code review to a review agent that checks the diff against the spec
5. Commit — stages and commits on approval, retries on rejection (up to 3 times)
6. Update — marks the task done in the plan
7. Restart — after successful task completion, it restarts the loop with fresh context

The loop exits when all tasks are complete, the agent stalls (no changes for 3 consecutive iterations), or it hits a blocker that needs human intervention. It will let you know how it feels about each outcome.

marvin (orchestrator loop)
├── Orchestrator agent     — coordinates, never writes code
│   ├── Build agent        — implements tasks, runs validation
│   └── Review agent       — reviews diffs against specs
├── Harness (claude | opencode)
│   ├── claude             — drives Claude Code CLI
│   └── opencode           — drives opencode CLI
└── Sandbox (optional)     — filesystem + network restrictions

The orchestrator is the only agent that touches the plan file. Build and review agents operate in isolated contexts with restricted permissions: the build agent can't git commit or git push, and the review agent only has read access plus git inspection tools. Nobody gets to do anything destructive. Marvin wouldn't trust them. Marvin doesn't trust anyone.

Requires Node.js >= 24 and pnpm.

pnpm add -g github:madeleineostoja/marvin

marvin <plan.md> [options]

Create a marvin.json in your workspace root:

{
  "harness": "claude",
  "maxIterations": 50,
  "preflight": "tsc --noEmit",
  "models": {
    "orchestrator": "sonnet",
    "build": "sonnet",
    "review": "opus"
  },
  "sandbox": {
    "enabled": true,
    "domains": ["registry.npmjs.org"]
  }
}

The plan file is a markdown document listing tasks for Marvin to work through. Each task should have a clear description and acceptance criteria. Tasks can reference separate spec files for detailed requirements. Each task should use a - [ ] markdown checkbox pattern.

Marvin updates the plan file as it works — marking tasks done with dates and adding notes about discovered issues.

Without a plan, Marvin refuses to start — even its bottomless despair has limits.

Marvin is deeply paranoid. This is, for once, a feature.

• Branch protection — refuses to run on main
• Lock file — prevents concurrent runs (.marvin/.lock). Reclaims stale locks automatically if the holding process is dead.
• Sandbox — optional filesystem and network restrictions via @anthropic-ai/sandbox-runtime. Denies reads to ~/.ssh, ~/.aws, ~/.gnupg, and other sensitive directories.
• Stall detection — stops after 3 consecutive iterations with no working tree changes
• Process cleanup — kills entire process trees between iterations, including escaped children

Each iteration writes a log to .marvin/logs/iteration-N.log with tool call traces, timing, and exit codes.