<p align="center"> <img src="docs/assets/mavericks-os-banner.png" alt="Mavericks OS — reliable, auditable delivery for Claude Code" width="100%"> </p>

Mavericks OS for Claude Code

Reliable, auditable delivery for Claude Code agents.

Mavericks persists project state across sessions, routes work through specialised roles, and blocks backlog/task drift before commit.

Built for operators and small teams running agent-driven development across multiple repositories.

323 tasks · 25 waves · 12.5 weeks — tracked from one central backlog across 10 of the 20 Git repositories of a live AWS system (15 active Lambda functions). Measured through 13 July 2026.

See it in action · Why Mavericks is different · Quick start

Close it. Come back tomorrow.

Close Claude Code, come back tomorrow — the wave goal and handoff are handed to you, not reconstructed from chat history.

Anyone juggling more than one project knows this trap: you close the laptop mid-thought, get pulled away, and by the next session you're rebuilding what you were doing from memory or a long scroll of chat history — both slow, and easy to get wrong. Mavericks writes that down instead: what was in progress and what to do next live in the project itself, so the next session opens with a clear starting point, not a guess. See Pick up exactly where you left off.

Three results

• Close it, come back tomorrow — no state archaeology. State lives in versioned artifacts; every session resumes from written state, not a chat log. See Pick up exactly where you left off.
• Auditable runs. You can see — and diff — why the system did what it did, because state and decisions live in files, not model memory. See What actually carries over between sessions.
• Drift caught before commit. A validator blocks out-of-sync BACKLOG/TASK_STATUS before it reaches a commit. See A status that isn't written down isn't real.

Case study: Synth

Synth is a production AWS system of 20 Git repositories and 15 active Lambda functions. Mavericks ran the operation from a single control repository whose central backlog declared 10 of those 20 repositories as task targets — the coordination is production-exercised, not merely designed, and it comes with the honest caveats of an N=1, no-control-group observation.

| Metric | Value | |---|---| | Repositories in the Synth system | 20 | | Repositories declared as task targets | 10 | | Active Lambda functions (live prod) | 15 | | Tasks reaching merge or beyond | 323 (242 merged + 81 deployed_prod) | | Multi-repo tasks (target > 1 repo) | 19 | | Delivery waves | 25 | | Session checkpoints | 81 | | Control-repo commits, Mavericks era | 523 (vs 364 baseline) | | Window | 17 Apr – 13 Jul 2026 (~12.5 weeks) |

This is an observational, N=1 case study — one operator, one control backlog, no control group — so the numbers show operational continuity and auditability across a coordinated system, not causal productivity.

Read the full methodology, findings, and limitations →

Why Mavericks is different

Most agent workflows fall into one of three categories below. Mavericks overlaps with parts of each, but its shipped combination — versioned state, a validator gate, specialised roles, and production-exercised multi-repo coordination — is what the table below is comparing.

| Capability | Ad-hoc prompting | Chat-memory tools | Single-repo task boards | Mavericks | |---|---|---|---|---| | Session continuity across restarts | ❌ | ⚠️ recall, not authoritative state | ⚠️ requires manually re-reading the board | ✅ versioned artifacts (BACKLOG.md, TASK_STATUS.md, PROCESS_STATE.json) | | Auditable, diffable decision history | ❌ | ❌ | ⚠️ issue/comment history, not structured | ✅ state and decisions live in files, diffable in git | | Automated drift detection before commit | ❌ | ❌ | ❌ | ✅ validator blocks out-of-sync backlog/task state (exit 2) | | Role-specialised execution & review | ❌ | ❌ | ⚠️ manual assignment | ✅ spec'd sub-agent roles (developer, QA, UX, security, docs, architect…) | | Multi-repository backlog coordination | ❌ | ❌ | ❌ single repo | ✅ production-exercised — 10 of 20 repos in the Synth case study |

Legend: ✅ built-in and shipped · ⚠️ possible, but manual or partial · ❌ not addressed

Quick start

Before you run this: Mavericks defaults to autonomous tool execution (bypassPermissions, no per-action confirmation prompts once a session starts). See Security model below for exactly what that means and how to opt out.

There are two different things you might want to do here — try Mavericks, or adopt it into a project you already have. They're separate steps.

Try the demo

One command, no follow-up needed:

curl -fsSL https://raw.githubusercontent.com/yahor-punko/mavericks-os/main/install.sh | sh -s -- --demo

This clones Mavericks to $HOME/.mavericks, prompts for consent on your terminal (the bypassPermissions disclosure — see SECURITY.md for exactly what that means and how to opt out), then runs a narrated, throwaway walkthrough of the operator loop against a disposable fixture — no docs required.

To re-run the demo later without reinstalling:

"$HOME/.mavericks/scripts/mavp-operator" --demo

(Use the absolute path above, not a relative ./scripts/mavp-operator — that only works from inside the Mavericks checkout itself.)

Add Mavericks to a project

The one-liner above only clones the framework — it does not touch your own project. Adopting Mavericks into a project is a separate step, run against the checkout the demo just created:

node "$HOME/.mavericks/scripts/mavp-install.js" /path/to/your-project

See Manual install below (or docs/core/BOOTSTRAP_GUIDE.md for the full step-by-step) for what this creates and how to configure it.

Your first session

1. Restart your editor (Claude Code or VS Code) so it picks up what was just installed.
2. Type /session-start and let your agent take it from there.

A session is one sitting: you tell your agent where things stand or what you'd like to do next, it does the work, and when you're ready to stop for the day you ask it to close up — it remembers where things left off for next time.

A wave is the bigger container: a batch of work aimed at one goal you set together with your agent. Once that goal is met, you close the wave together and move on to the next one.

Requirements

• Node.js 20+
• Claude Code CLI (claude)
• git

Manual install

For people who'd rather not curl | sh:

Step 1 — Get Mavericks onto your machine

Clone this repository somewhere on disk, e.g.:

git clone https://github.com/yahor-punko/mavericks-os.git <path-to-mavericks>

Everything below refers to that checkout as <path-to-mavericks>.

Step 2 — Bootstrap a new project

From your own project's directory (or pointing at it):

node <path-to-mavericks>/scripts/mavp-install.js /path/to/your-project

Use --check first to preview what would happen without writing anything:

node <path-to-mavericks>/scripts/mavp-install.js --check /path/to/your-project

Runs non-interactively (no prompt) when invoked from an agent's Bash tool or piped/CI, or explicitly via --yes / -y; at a real terminal without either it still asks Create N file(s)...? [Y/n].

If you ask an agent to install Mavericks from a session where shell access is denied, it can't — run the one command above yourself (terminal, or the ! prefix in Claude Code). This one-time human step is deliberate: the person running the installer consents to the prompt-free bypassPermissions default it configures (see SECURITY.md). In prompting permission modes a single approval suffices instead. Later sessions inherit the configured permissions and the agent operates autonomously.

This creates, in your-project/:

• scripts/mavp-operator — a bash wrapper that delegates to this Mavericks installation
• scripts/mavp-operator-agent.js — project-specific session-start summary
• scripts/mavp-operator-close-session.js — end-of-session ritual
• BACKLOG.md, TASK_STATUS.md, PROCESS_STATE.md, PROCESS_STATE.json — live state artifacts, from templates
• .claude/agents/*.md, .claude/skills/*/SKILL.md, .claude/rules/*.md — sub-agent specs, skills, and rules, copied from this repo
• .claude/settings.json / .claude/settings.local.json — shared and personal Claude Code settings (see Security model below)

Pass --transcript-archive to opt into a gitignored session-transcript archive at .mavp/transcripts/, with retention bounded via the MAVP_TRANSCRIPT_RETENTION_DAYS env var — off by default. See docs/core/BOOTSTRAP_GUIDE.md for details.

Core framework scripts (the operator library, dashboard, validator) are not copied into your project — the generated scripts/mavp-operator wrapper runs them directly from this Mavericks checkout.

The wrapper resolves the Mavericks install location in this order: an explicit MAVERICKS_HOME env var, if set, always wins; otherwise $HOME/.mavericks — the canonical default, and where install.sh clones Mavericks — is used if it exists; otherwise $HOME/Documents/mavericks is used as a legacy fallback. If you cloned Mavericks somewhere else entirely, set MAVERICKS_HOME to that path (e.g. in your shell profile or before invoking the wrapper):

export MAVERICKS_HOME=<path-to-mavericks>

The wrapper also exports MAVERICKS_PROJECT_ROOT automatically when it runs, pointing framework scripts at your project's artifacts rather than the Mavericks checkout itself — you don't need to set this one yourself.

For the full step-by-step, including editing PROCESS_STATE.json, adding your first tasks, and setting up the pre-commit validator hook, see docs/core/BOOTSTRAP_GUIDE.md.

Updating Mavericks

Updating is two steps — one for the shared framework checkout, one per project.

1. Update the framework checkout. Bootstrapped projects run core scripts directly from the checkout, so this one step updates the framework for every project at once:

git -C "$HOME/.mavericks" pull --ff-only    # use your <path-to-mavericks> if you cloned elsewhere

Re-running the curl | sh installer does the same thing — it is idempotent and pulls an existing checkout instead of re-cloning.

2. Re-sync each bootstrapped project. The files the installer copied into your project (.claude/ agents, skills, rules, hooks, and the wrapper and project scripts) don't update themselves. From each project's directory:

./scripts/mavp-operator --install --update .

This overwrites the copied framework files with the latest versions and records the new framework version in PROCESS_STATE.json. It never touches your task state — BACKLOG.md, TASK_STATUS.md, and the rest of PROCESS_STATE.json are left alone. Pass --no-hooks to skip the hooks refresh, or use --hooks-only to refresh only the hooks.

You don't need to watch for releases: when a project's recorded framework version falls beh