How MARVIN fits together

MARVIN sits around Claude Code. It doesn’t replace the model or the CLI. It decides what a session knows when it starts, gives it playbooks to load on demand, and runs work in the background while you’re away, with gates you control before anything lands on main.

Each feature below has a page with how it works, how to use it, its limits, and links to the decision record and the source. Every page shows a status badge and the date its facts were last checked against the running system.

The system on one page

you ─► Claude Code session ─► memory + skills loaded on demand
              │
              ▼
        ticket on GitHub ─► pipeline (worktree, plan, build, measure) ─► PR with evidence
                                                                        │
                                        you approve ─► merge gate ─► main
                                                                        │
        dashboard + map ◄── health checks, logs, usage ◄────────────────┘

Release status

Badge	What it means	The rule behind it
Released	Documented, on in daily use, changes go in the changelog	Merged to `main` and there’s run evidence: a loaded job, a log written in the last 7 days, an installed app
Built, in testing	Merged and runnable, but opt-in, in shadow mode, or not proven in daily use yet. It may change	Merged to `main`, but behind a flag, in shadow mode, or with no run evidence yet
Planned	Nothing to use yet	An open ticket or an ADR, no merged code. Planned work is on the roadmap only, never a feature page, never a date

“Verified on” is the day someone checked the page’s facts against the code and the machines that run it. The badges come from one file, site/src/data/features.yaml, and the build fails if a Released feature has no evidence.

Features

34 released, 8 built and in testing, all verified on or before Nov 2, 2026. Planned work is on the roadmap.

Memory and knowledge

Memory and context retrievalReleased
Four kinds of memory notes; vector search re-ranked by keyword and fused by rank, with tag matching as the fallback.
SkillsReleased
33 on-demand playbooks (TDD, diagnose, research, grill, handoff, audit and more), loaded only when a task needs them.
LexiconReleased
A shared vocabulary loaded every session, so a term means the same thing tomorrow.
Session start and shared "working on"Released
A hook runs the start-of-session checks; parallel sessions see what each other are editing.
qa-agent knowledge baseReleased
A store of best practices and past outcomes, queried on request before unfamiliar library work.
Routing classifierReleased
An embedding classifier reads the first prompt and suggests the model or profile that fits.

Works while you're away

Ticket pipelineReleased
A ticket becomes a PR on its own: isolated worktree, planner and executor, measured result, evidence in the PR.
Parallel dispatchReleased
Several tickets at once, with per-machine and per-project slots and disk and GitHub budget guards.
Pipeline stage stripReleased
A stage-by-stage strip on every PR and ticket card, showing where a build stopped.
Failure breakerReleased
Every failure is logged with a cause; the pipeline pauses itself after 3 tickets fail the same way in 2 hours.
Launcher and output contractsReleased
Every model run goes through one launcher, and every producer of output needs a named consumer.
Helper tabsReleased
Helper agents start in labelled terminal tabs and finish on their own exit, not on a timer.
Plan-first buildsReleased
Builds use the plan's normal slots first and only spill over to API credit when those are busy.

You stay in charge

Merge gateReleased
Rebase, re-run the tests the change can affect, check the screenshots, and log every refusal with its reason.
Memory-sized parallel tests in buildsBuilt, in testing
The pipeline's build step runs its Python tests in parallel, with workers sized to free memory.
DecisionsReleased
When a PR needs the owner to choose, it asks with tickable options, and the merge server enforces the answer.
GitHub gateReleased
One gh wrapper for every call, with a rate budget, a call log and rules for what a PR body must carry.
Safety monitor and quarantineReleased
Scores autonomous output for risk; flagged items wait for review, one card at a time.
Merge queueBuilt, in testing
Approve queues the merge, and MARVIN works out the order.
Auto-merge for low-risk PRsBuilt, in testing
Scores each PR's risk and would merge the low-risk ones without asking.

See what it's doing

Dashboard appReleased
MARVIN.app, a desktop mission control: Health, MR Review, Docs, Activity and more.
Health checksReleased
Health checks discovered from the scheduler, across every machine and job, shown in the Health tab.
ActivityReleased
A ranked "needs you" queue, the helper agents at work, and each project's goals.
Docs tabReleased
Every project's docs and ADRs, read live, private repos included.
ProposalsReleased
Big ideas written for a lay reader, reviewed next to the PRs.
Boot sequence and identityReleased
A celestial-navigation boot that shows the real health verdict, and the constellation-M icon.
The mapReleased
A 3D map drawn from the real system, published as a privacy-checked snapshot and used as a live wallpaper.
Usage accountingReleased
Token, tool and GitHub usage per machine, over 24 hours, 7 days and 30 days.
MARVIN Mobile (iPhone)Built, in testing
MARVIN on the iPhone over a private network.

Machines and upkeep

Cross-machine syncReleased
Two-way code and state sync between machines, with a union merge for append-only files. It has failures, and logs them.
Engine and instance splitReleased
The engine is public; each person's state lives in their own private instance repo.
Disk ledger and trimReleased
Forecasts disk use, trims automatically, and deletes by what a file would cost to replace.
Worktree cleanupReleased
Backs up leftover edits to a branch, then removes stale worktrees.
Versioning and changelogReleased
Labels on a merged PR set the version bump and write the changelog line.
Support linkReleased
Two MARVIN installs connect so one can help the other, and every fix is verified.
Project onboardingBuilt, in testing
One command wires a new repo into MARVIN.
Third machine on LinuxBuilt, in testing
A Linux box takes test runs, benchmarks and scans off the Macs.
Peer care and nightly resetBuilt, in testing
The machines look after each other and reset safely at night.
History storeBuilt, in testing
One local database per machine for the history every tab reads.

Research and measurement

Research colony, digests and morning briefReleased
Feeds and papers turn into a daily digest, a research digest and one morning brief.
BenchReleased
A/B runs of profiles on cost and correctness, and a retrieval eval with the method in the open.
Code graphReleased
A knowledge graph of the code, rebuilt after every merge, with a health check when it falls behind.

Words MARVIN uses

From the repo’s CONTEXT.md, the shared glossary.

Term	Meaning
Engine	The public MARVIN code anyone can download. It holds no person’s or machine’s data.
Instance	One owner’s private state for an engine: plans, screenshots, tickets, accounts, feature choices. One engine, many instances.
Skill	One capability inside MARVIN: a `SKILL.md` playbook loaded when a task needs it.
Add-on	A feature that’s off until the owner turns it on. Not the same thing as a skill.
Ticket	A GitHub issue the pipeline can pick up and turn into a PR.
Merge gate	The checks between your Approve and `main`.
Decisions	Questions a PR asks the owner as tickable options, never in prose.
ADR	An architecture decision record in `docs/adr/`: what was decided, why, and what was rejected.

Reading an ADR

Every feature page links its ADRs. They’re short and follow one shape: Status (Proposed, Accepted, Superseded), Context (the problem at the time), Decision, and Consequences, often with the alternatives that were turned down. A Proposed ADR describes a direction, not shipped behaviour. When the code and an ADR disagree, the feature page follows the code and says so.