Meeseeks

+--------------------------------------------------------------+
|                                                              |
|    I ' M   M R   M E E S E E K S !   L O O K   A T   M E !   |
|                                                              |
|    THIS BOX IS UNATTENDED. NOBODY IS WATCHING IT.            |
|    PERMISSIONS HAVE BEEN DISABLED FOR YOUR CONVENIENCE.      |
|    NOT AVAILABLE IN PRODUCTION. VOID WHERE PROHIBITED.       |
|                                                              |
+--------------------------------------------------------------+

⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢰⡆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣤⣤⣼⣿⣿⡆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⠀⣠⣾⣿⣿⣿⣿⣿⣿⣿⣿⣷⣦⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣠⣴⣾⣿⢃⣾⣿⣿⣿⡿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣆⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⣠⣾⣿⡿⠛⠉⠀⣾⣿⣿⣿⣿⣿⣿⡯⣽⣿⣿⣿⣿⣿⣿⣿⣿⡆⢀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⣠⣾⣿⠟⠁⠀⠀⠀⢸⣿⣿⣿⣿⣿⣀⣹⣄⣩⣿⣿⣿⣿⣿⣿⣿⣿⣿⢸⣷⣄⠀⠀⠀⠀⠀
⠀⠀⠀⢀⣾⣿⠟⠁⠀⠀⠀⠀⠀⢰⣾⣽⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣻⣯⢻⣿⣿⡟⠈⠻⣿⣷⡀⠀⠀⠀
⠀⠀⢠⣿⡿⠃⠀⠀⠀⠀⠀⠀⠀⠈⣿⣝⣿⣿⣿⣿⣿⣿⣿⣿⣿⣫⣿⣷⣿⣿⡿⠁⠀⠀⠘⣿⣿⡄⠀⠀
⠀⢠⣿⡿⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠹⣿⣿⣾⣿⣿⣿⣿⣽⣿⣿⣿⣿⣿⣿⡿⠁⠀⠀⠀⠀⠈⣿⣿⡄⠀
⢀⣿⣿⠃⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠹⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠋⠀⠀⠀⠀⠀⠀⠀⠘⣿⣿⠀
⢸⣿⡏⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⣨⣾⣿⣿⣿⣿⣿⡿⠿⠟⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢹⣿⡇
⣿⣿⠇⠀⠀⠀⠀⠀⠀⠀⠀⣀⣤⣶⠿⠋⣿⣿⣿⣿⣿⣿⣿⠿⣶⣤⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⣿⣷
⣿⣿⠀⠀⠀⠀⠀⢀⣤⣶⠿⠛⠉⠀⠀⢸⣿⣿⣿⣿⣿⣿⡏⠀⠀⠈⠙⠻⠷⣶⣤⣀⠀⠀⠀⠀⠀⠀⣿⣿
⣿⣿⡄⠀⢀⣴⣾⠟⠋⠁⠀⠀⠀⠀⠀⣿⣿⣿⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀⠀⠙⠻⢷⣦⣄⠀⠀⢸⣿⣿
⢹⣿⡇⠐⣿⣯⡀⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣧⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠙⣻⣷⡄⣸⣿⡇
⠈⣿⣿⡀⠈⢻⣿⣦⡀⠀⠀⠀⠀⠀⣾⣿⣿⣿⣿⣿⣿⣿⣿⡀⠀⠀⠀⠀⠀⠀⠀⣀⣴⣾⡿⠋⢀⣿⣿⠁
⠀⠹⣿⣷⡀⠀⠙⢿⣿⣷⣄⡀⠀⢀⣿⣿⣿⣿⣿⣿⣿⣿⣿⣇⠀⠀⠀⢀⣠⣴⣾⣿⠟⠋⠀⢀⣾⣿⠇⠀
⠀⠀⠹⣿⣷⡀⠀⠀⠙⢿⣿⣿⣶⣸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣀⣴⣾⣿⣿⡿⠛⠁⠀⠀⢀⣾⣿⠏⠀⠀
⠀⠀⠀⠙⢿⣿⣄⠀⠀⠀⣙⠛⣿⢻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⢸⣿⣿⣿⣱⡆⠀⠀⠀⣠⣿⡿⠃⠀⠀⠀
⠀⠀⠀⠀⠈⠻⣿⣷⣄⠀⠻⣧⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣏⠿⣿⡿⠟⠀⢀⣠⣾⣿⠟⠁⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠈⠻⢿⣿⣦⣌⡉⠁⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇⠀⢀⣠⣴⣿⡿⠟⠁⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠙⠻⢿⣿⣷⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣶⣾⣿⡿⠟⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠉⠛⠛⠿⠿⠿⠿⠿⠿⠿⠿⠛⠛⠉⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀

You press the button. Something appears, does one job, and stops existing.

Meeseeks is a Claude Code plugin. One command hands a specification to an autonomous loop that designs, builds, gates, audits and ships it — unattended — until it passes an enterprise definition of done, or the budget dies.

/meeseeks ./PRD.md                              # build an existing spec
/meeseeks "a link shortener with an admin page" # build from an idea
/meeseeks                                       # improvise: it invents its own
/meeseeks --improve "error handling"            # the repo already exists: find whats wrong, fix it
/meeseeks "an idea" --confirm-prd               # stop after committing PRD.md for a human read

/meeseeks ./PRD.md --deadline=90                # a 90-minute wall clock; off unless asked for
/meeseeks ./PRD.md --give-them-the-box          # unsupported: permits nested runs, arms a clock

The three control flags, precisely:

• --confirm-prd — author or ingest and commit PRD.md, then exit before Oracle, design, build, or any unattended loop work. Review the file and start the accepted run explicitly with /meeseeks ./PRD.md; this is a checkpoint between invocations, not a paused live run.
• --deadline=<minutes> — a wall clock on the whole run, checked between iterations. Off unless given; the ordinary ceilings are completion or budget, so most runs never want one. The flag outranks deadlineMs in config (a flag is this session's instruction; config is the target's standing one), fractions work (--deadline=0.5), and anything unreadable refuses the run rather than defaulting — a ceiling that cannot be read is not a ceiling.
• --give-them-the-box — permits a run inside a run, to depth two, and arms a 30-minute wall clock unless --deadline set one. Depth bounds recursion, but nothing bounds how many nested runs one iteration starts — which is why --deadline=0 (explicitly no clock) is refused in combination with the box: unbounded-and-nested is the one shape with no limit at all. Everything else still holds — .meeseeks/ stays guarded, review stays cold, nothing defaults to pass, and same-tree nesting is still refused by the run lock regardless.

Pre-production only. Build children run with --dangerously-skip-permissions. Point this at a throwaway repository and nothing else. The plugin's own guard hook is the floor under that, not a substitute for choosing the right directory.

A throwaway repository does not isolate the host. Meeseeks currently establishes no CPU, memory, process-count, disk-space, or workspace-growth quota, and Claude's documented Bash sandbox controls filesystem and network access rather than those resources. For unattended use, provide a disposable OS account, VM, container, or equivalent host boundary with explicit resource limits. PLAN item 84 owns measurement of the actual child boundary; no stronger guarantee is implied here.

Current release status. The guarantees described below are design invariants, not a claim that the current release enforces every one perfectly. The independent release gate is currently CHANGES REQUESTED with open false-completion, termination, evidence, and trust-boundary defects in REVIEW.md. Until those findings close, treat SHIPPED as evidence to inspect, never as production authorization.

Why a Meeseeks

The joke earns its place because the canon maps onto the machinery:

That last row is the point. The most canon-accurate behaviour is the one the architecture refuses by default — a box that hands out boxes is not a feature, it's the disaster the episode is about. /meeseeks does not spawn /meeseeks, enforced at the driver and at the hook.

--give-them-the-box permits it anyway, because a joke that only ever prints a refusal is one nobody gets to see happen. It is unsupported, loud, capped at depth two, and arms a wall clock — depth bounds recursion, but nothing bounds how many nested runs one iteration starts.

What actually happens

/meeseeks <PRD | "idea" | nothing>
  │
  ├─ 0. PRD          author or ingest the specification
  ├─ 1. Design       architecture docs, and a declaration of what this project IS
  │                  (cli? api? web-ui? — it decides which gates even apply)
  │
  ├─ 2. Build        one builder child, given a brief and nothing else
  ├─ 3. Gates        build · lint · types · unit · e2e · security-audit · mutation,
  │                  plus provisioned quality gates (impeccable, knip, semgrep,
  │                  schemathesis) and any operator:* gates the config declares.
  │                  Deterministic, exit codes only, no model involved
  ├─ 4. Ratchet      every test id that has ever passed must still pass
  ├─ 5. Review       three cold auditors, separate processes, unanimous or no ship
  └─ 6. Ship         tag, or go round again

It ends in exactly one of four states, and three of them are failures:

SHIPPED · STALLED · BUDGET · ABORTED

The four things that make it safe

1. The ratchet is monotonic. .meeseeks/state.json holds every test id that has ever passed. Drop one and the tree hard-resets, the regression becomes the next task, and nothing else proceeds. This is the single mechanism that turns an infinite loop into a terminating one.

Since 0.112.0 the reset is scoped first: the driver restores only the files a regression implicates, re-runs the suite to confirm the ids came back, and falls back to the full reset if they didn't. A whole-tree reset was measured discarding 15.2M tokens of unrelated work in one run.

It starts protecting as soon as the suite proves an id, not when the whole tree is green. Until 0.121.0 the ratchet was written only by an iteration that passed every gate and was reviewed — so case I held 71 passing tests across 8 iterations with state.json never written, and breaking one would have gone unnoticed. Ids are now banked whenever the unit gate passes, because that is the claim being made: the suite ran and produced a report. The reset target still only moves on a fully good iteration.

2. The builder cannot judge its own work. Review happens in separate claude -p processes. The Driver does not supply the build log, iteration history, or Builder framing; this is deliberate context starvation, not a filesystem seal. Three auditors — security, correctness, design — each owning different requirement ids. It is never a subagent, and that is not an optimisation waiting to happen.

3. Nothing defaults to pass. Missing evidence, unparseable reviewer output, a crashed gate, a timeout, a requirement no auditor judged — all fail. There is no catch { return pass } anywhere in this repository, by rule.

4. The guard hook is not editable by what it guards. Processes inside a run may not write anything under .meeseeks/, at any depth, including files that don't exist yet — the rule is positional, not a list of names. It also protects itself. Outside a run these are ordinary files and you edit them however you like.

Install

/plugin marketplace add trevor-ryan-burkholder/meeseeks
/plugin install meeseeks@meeseeks

If a fix seems not to work, check this first. Claude Code caches plugins by <marketplace>/<plugin>/<version>/. An update at an unchanged version resolves to the old folder and silently runs the previous build. npm run release-check refuses a release whose loader files moved without a version bump; npm run slice-check -- verify fingerprints that same loader boundary plus the package manifests while it runs the validation gates.

This project was previously called dare-to-be-stupid. The rename is a fresh install, not an upgrade — if both are present, /dare and /meeseeks are two different programs. Remove the old one.

Requirements: Node ≥ 22.12 with npm/npx, git, an authenticated Claude Code 2.1.226 through 2.1.235 (inclusive), and network access to the npm registry. Run it only in a throwaway, non-production Git repository with at least one commit and a clean working tree; the ratchet resets to commits and may discard uncommitted work. Preflight checks all of those conditions, scaffolds .meeseeks/config.json when absent, refuses tracked .meeseeks/ state, and reports every blocking repair before the unattended Driver starts.

The version range is measured, not a semantic-version promise; scripts/claude-compat.mjs is the runtime authority and records the evidence required to move either bound. After preflight, the Driver makes an independent non-interactive authentication probe at the run boundary before any role child. A supported version and successful login do not by themselves prove immutable CLI identity; REVIEW F28 and PLAN item 83 own the remaining invocation-identity repair and evidence. No runtime dependencies — the Driver is node: builtins plus bounded subprocesses.

The run provisions project-local quality tooling when it becomes applicable: Impeccable is required; Knip, Semgrep, and Schemathesis are attempted and degrade to explicit warnings when unavailable; Gitleaks is detect-only and must be installed separately to enable that gate; and Chromium is installed when a Playwright gate becomes applicable. Python-based optional tools require python3 and pip. The target's own SDK and services remain host prerequisites—for example, the .NET SDK for a .NET repository. If sandbox.enabled is armed on Linux/WSL, install both bubblewrap and socat; macOS uses the operating system's seatbelt sandbox.

Process-tree cleanup is currently evidenced on POSIX/WSL2. Native Windows descendant cleanup remains OPEN under REVIEW F11 / PLAN item 65; do not rely on a timed-out child being fully reaped there.

Configuration

Everything lives in .meeseeks/config.json, which the guard protects during a run — so a gate declared here is one the builder cannot delete.

You don't have to hand-author it. From the target repository, invoke the installed plugin's script by its real path — the relative path scripts/configure.mjs would look inside the target and is usually wrong:

cd /path/to/target
node /absolute/path/to/meeseeks/scripts/configure.mjs

The plugin details shown by /plugin identify the installed copy; a source checkout works too. The wizard walks the common settings as prompts using the same validator as the driver. Blank keeps the shown default, and keys it does not ask about survive untouched. --show prints the config as written (file merged over defaults) without writing anything; run-time env overrides are not shown. The example below is a common-settings excerpt, not the complete schema; scripts/config.mjs::defaultConfig() is the machine authority and DESIGN.md §10 documents every field.

{
  "maxIterations": 25,
  "tokenCeiling": 4000000,
  "costCeiling": 50,
  "deadlineMs": 0,
  "extraGates": [],
  "race": { "enabled": false, "n": 3, "after": 2 },
  "oracle": { "enabled": false },
  "sandbox": { "enabled": false }
}

A zero token or cost ceiling disables that ceiling. A zero deadline is off unless --give-them-the-box arms one. Put target-specific operator gates in extraGates.

Budget arithmetic, measured rather than guessed. The defaults are conservative stop signals: the 4M-token or $50 ceiling will commonly bind before the 25-iteration limit. Completed iterations have cost 5–9M tokens in measured dogfood, which is a planning range rather than an upper bound. Phase 0/1 spend arrives before the loop, a child can exceed a ceiling before returning, and the parallel panel can have three reviewers already in flight when a breach becomes visible. A ceiling therefore bounds whether more work starts; it cannot cap work already in flight. Raise or disable one only as an explicit operator decision.

The % of budget remaining line reports the tightest of iterations, tokens and dollars — the limit that will actually end the run, not the most flattering one.

Output style

The Meeseeks voice is cosmetic and rendered at output only. It never informs a gate result, the ratchet, or reviewer JSON.

MEESEEKS_STYLE=plain    # bypasses it completely

Never styled, in either mode: code, identifiers, file paths, JSON, commit messages, stack traces, test names, error text. Failure output is verbatim. A garbled stack trace is funny once and then it is a broken tool.

SHIPPED is the only happy exit — the task is done and the Meeseeks ceases. The other three end in I JUST WANNA DIE!!!, each with its own lead-in, because an operator who can't tell a stall from an exhausted budget from an abort has lost information to a punchline.

Working on this repo

Read docs/INDEX.md first for document authority and task-specific read routes. Historical ledgers are evidence, not implementation instructions. Claude Code follows CLAUDE.md's autonomous loop: finish and commit complete slices, continue past review-pending repairs, and stop for Codex only at a documented dependency or release boundary.

npm run lint          # style and obvious errors
npm run typecheck     # jsdoc via tsc-checkJs; we are not adding TypeScript
npm test              # tier 1: unit + fixture, nothing but node
npm run test:integration   # tier 2: real git, node, npm; no network or external API
MEESEEKS_LIVE=1 npm run test:live   # tier 3: real claude -p model calls
npm run release-check # refuses loader changes without a version bump
npm run slice-check -- verify # gates one stable loader + package-metadata fingerprint

The tiers are separately runnable on purpose. claudeArgs was once unit-tested and correct while the fault lived in another program's parsing of the array it built — no assertion about that array could have found it. Anything whose contract is owned by a different binary needs one live check, not more assertions. Tier 2 earned this on its first run by finding a git too old for --initial-branch.

The live tier is armed by MEESEEKS_LIVE=1 and fails without it rather than skipping, because a green tick for a suite that made no API call is a lie the reader takes for coverage.

Do not run /meeseeks against this repository. It builds the loop; it is not run by it.

Status

Pre-1.0 and honest about it. DESIGN.md is the product specification; CONSTITUTION.md owns repository invariants; docs/INDEX.md routes every other authority. HANDOFF.md carries current measured state and routes the full execution chronology, including what was not verified, to the frozen archive.

Measured, not asserted: twenty-plus dogfood runs against real throwaway projects, two of which reached SHIPPED. Cold review was 73% of a run's wall clock while the panel ran sequentially; the parallel panel (0.143.0) now runs the reviewers concurrently, so the panel costs its slowest reviewer's wall clock rather than the sum. Live-verified in real runs, not just unit tests: the ratchet's hard reset and scoped restore, the stall and wall-clock endings, the repeated-regression and stuck-gate notices, the security-pin escalation, the race executing end to end, and the tracked-state refusal. The full audit of what has never been exercised is preserved in docs/history/HANDOFF-through-0.161.0.md.

Disclaimer

This is an unofficial fan project. Its personas — "Mr. Meeseeks" and any other characters, catchphrases, or references it uses — are parody and homage in a developer tool, protected as such, and are the property of their respective owners.

meeseeks is not affiliated with, endorsed by, sponsored by, or associated with Adult Swim, Cartoon Network, Warner Bros. Discovery, the creators or rights holders of Rick and Morty, or any other associated party. All referenced names, characters, and trademarks belong to their respective owners; no ownership of or affiliation with them is claimed or implied.