\n\n# Mutter\n\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/arnaudovproject/mutter)\n\n**Mutter** brings a small **on-disk workspace** (folder **`.mutter/`**) into your repository so AI coding agents can **remember** architecture, tasks, and plans between sessions—without loading the whole tree into context. The same workflow patterns work across **Claude Code**, **Cursor**, **OpenAI Codex**, and **OpenCode**.\n\n| Section | Best for |\n|---------|----------|\n| [Who is Mutter for?](#who-is-mutter-for) | Decide if this matches your workflow |\n| [Recommended first path](#recommended-first-path) | Install and first commands (Claude Code) |\n| [Five-minute example](#five-minute-example) | One concrete pass: bootstrap → task → validate |\n| [Installation](#installation) | Cursor, Codex, OpenCode, and full Claude steps |\n| [Typical workflow](#typical-workflow-your-repo) | Day-to-day and before-merge habits |\n| [Skills](#skills-most-used-first) · [Workspace CLI](#workspace-cli) | Reference tables |\n\n---\n\n## Who is Mutter for?\n\nMutter fits **developers and teams** who already use (or plan to use) **AI coding agents** on **medium and large codebases** and want:\n\n- **Project memory on disk**—tasks, plans, architecture notes, and logs—not only chat history\n- **Repeatable agent behavior**—shared rules, checklists, and validation hooks\n- **Cheaper, calmer sessions**—indexes and small “context packs” instead of pasting the repo into every thread\n\nIf you only touch a repo once for a tiny change, you might not need this much structure. If agents work across **days, branches, or multiple PRs**, Mutter is aimed at you.\n\n---\n\n## Recommended first path\n\nIf you are new, start with **Claude Code** (the examples below use its **`/mutter:`** style):\n\n1. **Install the plugin** — follow [Quick install (Claude Code)](#quick-install-claude-code) (register the **repository root** that contains `.claude-plugin/marketplace.json`, then install **`mutter@mutter-plugins`**).\n2. Open **your project** in Claude Code and run **`/mutter:bootstrap`** — creates `.mutter/`, light entry files, and `scripts/mutter.py` when missing.\n3. Run **`/mutter:scan`** — builds incremental indexes under `.mutter/index/`.\n4. Run **`/mutter:help`** — see available skills and how they map to validation commands.\n\n**Other agents:** install Mutter for [Cursor](#cursor), [OpenAI Codex](#openai-codex), or [OpenCode](#opencode), then use the same *ideas* (bootstrap → scan → task/help); command names differ by **harness** (see [Typical workflow](#typical-workflow-your-repo)).\n\n---\n\n## Five-minute example\n\nIn **your** repository, with the plugin installed:\n\n1. **`/mutter:bootstrap`**\n2. **`/mutter:scan`**\n3. **`/mutter:task create \"Add user profile page\"`** (or any small, clear task title)\n4. Ask your agent to **execute the first unchecked step** in the generated task (keep one main outcome per turn while learning the flow)\n5. Before you call the task “done”, from the repo root: **`python3 scripts/mutter.py validate-task`**\n\nThat path covers the core loop; everything else in this README extends it (plans, PRD, reviews, CI helpers).\n\n---\n\n## Example: workspace CLI output\n\nAfter **bootstrap**, **`python3 scripts/mutter.py status`** shows where state lives and prints **`.mutter/state/current.json`** (active task, plan, and progress). Example:\n\n```text\nrepo_root: /path/to/your/project\nstate file: /path/to/your/project/.mutter/state/current.json\n{\n \"active_task\": null,\n \"active_plan\": null,\n \"active_workflow\": null,\n \"execution_progress\": null,\n \"paused\": false,\n \"updated_at\": null\n}\n```\n\n**`python3 scripts/mutter.py context-pack --out .mutter/context/session-pack.md`** writes a **Markdown bundle** (state, active task/plan slices when set, useful excerpts) you can attach when starting a **new** session—lighter than copying ad hoc file dumps.\n\n**Claude Code spelling:** skills are **`/mutter:`** (e.g. `/mutter:scan`). Some prose uses `/mutter scan`; Claude Code expects the **colon** form. Plugin id: **`mutter`** (lowercase).\n\n---\n\n## Quick install (Claude Code)\n\nRegister the **repository root** (the folder that contains `.claude-plugin/marketplace.json`), not `mutter-claude/`:\n\n```text\n/plugin marketplace add /path/to/mutter\n/plugin install mutter@mutter-plugins\n/reload-plugins\n```\n\nConfirm with **`/mutter:help`**.\n\nUse the **marketplace** flow only — do **not** symlink into `~/.claude/plugins`. Add the repo with **`/plugin marketplace add`**, then install **`mutter@mutter-plugins`**.\n\n---\n\n## What it does\n\n| Area | Description |\n|------|-------------|\n| **Project memory** | `.mutter/` holds architecture, tasks, plans, optional product spec (**PRD** at `.mutter/prd/PRD.md`), indexes, logs, and rules—without monolithic chat dumps. |\n| **Navigation** | Index shards and explicit paths first; avoid loading the whole repo into context when a task names a smaller slice. |\n| **Orchestration** | **Skills** (agent commands like **scan**, **task**, **plan**) plus the **workspace CLI** (`scripts/mutter.py`) for validation, preflight, **context-pack**, **agent-cadence**, and CI-oriented checks. |\n| **Discipline** | Small repo-root entry files (**`CLAUDE.md`**, Cursor rules); detail stays under `.mutter/`. |\n| **Multi-harness** | Parity across Claude Code, Cursor, Codex, and OpenCode—see [Code layout (by harness)](#code-layout-by-harness). |\n\n- Full spec: [`SPEC.md`](SPEC.md)\n- Harness / plugin development: [`docs/mutter-plugin-harness-reference.md`](docs/mutter-plugin-harness-reference.md)\n\n---\n\n## Code layout (by harness)\n\n| Agent | Location in this repo |\n|-------|------------------------|\n| **Claude Code** | `mutter-claude/` (`.claude-plugin/plugin.json`) |\n| **OpenAI Codex** | Same skills as Claude — `mutter-claude/.codex-plugin/plugin.json` → `mutter-claude/skills/` |\n| **Cursor** | `mutter-cursor/` (rules, skills, commands) |\n| **OpenCode** | Root `package.json` + `.opencode/plugins/mutter.js` (registers `mutter-claude/skills`) |\n\nCursor’s `mutter-cursor/skills/` is kept in sync with `mutter-claude/skills/` during Mutter development (`python3 scripts/sync_cursor_skills.py`).\n\nFrom here down, the README is **reference-heavy**: full install notes for every harness, the complete lifecycle workflow, and command tables. Skim the **quick links** table under the opening paragraph if you want to jump to one topic.\n\n---\n\n## Installation\n\n### Claude Code\n\n1. **Clone** (if needed): `git clone https://github.com/arnaudovproject/mutter.git`\n2. **Install** — follow [Quick install (Claude Code)](#quick-install-claude-code): marketplace path = **clone root** (the directory that contains `.claude-plugin/marketplace.json`). Example: repo at `/code/mutter/mutter` → `/plugin marketplace add /code/mutter/mutter`. Catalog name **`mutter-plugins`** ([`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json)); package under [`mutter-claude/`](mutter-claude/) installs as **`mutter@mutter-plugins`**.\n3. **Update** — `git pull`, then **`/reload-plugins`**\n4. **Uninstall** — `/plugin uninstall mutter`, then `/plugin marketplace remove mutter-plugins`\n\n**Local / dev** (no marketplace): from repo root, `claude --plugin-dir ./mutter-claude`; after edits, **`/reload-plugins`**.\n\nDocs: [Plugins](https://code.claude.com/docs/en/plugins) · [Plugins reference](https://code.claude.com/en/plugins-reference).\n\n### Cursor\n\n- **Team marketplace:** import this Git repo per [Cursor Plugins](https://cursor.com/docs/plugins). [`.cursor-plugin/marketplace.json`](.cursor-plugin/marketplace.json) maps the `mutter` entry to `./mutter-cursor`.\n- **Local dev:** symlink or copy so `mutter-cursor/.cursor-plugin/plugin.json` is at the **root** of the installed plugin, e.g. `ln -s /path/to/mutter/mutter-cursor ~/.cursor/plugins/local/mutter` — then **Developer: Reload Window**.\n\nDocs: [Plugins](https://cursor.com/docs/plugins) · [Reference](https://cursor.com/docs/reference/plugins.md). IDE routing (this repo does not ship `.cursor/`): [`docs/mutter-cursor-ide-routing.md`](docs/mutter-cursor-ide-routing.md).\n\n### OpenAI Codex\n\nSkills: **`mutter-claude/skills/`** · Manifest: **`mutter-claude/.codex-plugin/plugin.json`**.\n\n- **In this repo:** [`.agents/plugins/marketplace.json`](.agents/plugins/marketplace.json) points at `./mutter-claude` for local dogfooding / CI.\n- **In a consumer repo:** add a marketplace and install per [Codex Plugins](https://developers.openai.com/codex/plugins) and [Build plugins](https://developers.openai.com/codex/plugins/build).\n\nSkill names and YAML frontmatter align with Claude.\n\n### OpenCode\n\nRequires [OpenCode](https://opencode.ai). In `opencode.json` (project or `~/.config/opencode/opencode.json`), add to **`plugin`**:\n\n```json\n{ \"plugin\": [\"mutter@git+https://github.com/arnaudovproject/mutter.git\"] }\n```\n\nPin a revision by appending `#branch`, `#tag`, or `#sha`:\n\n```json\n{ \"plugin\": [\"mutter@git+https://github.com/arnaudovproject/mutter.git#main\"] }\n```\n\nRestart OpenCode. More: [`.opencode/INSTALL.md`](.opencode/INSTALL.md) · [OpenCode Plugins](https://opencode.ai/docs/plugins/).\n\n---\n\n## Typical workflow (your repo)\n\n**Harness spellings:** Claude → **`/mutter:`** · Cursor → palette **`mutter-`** (e.g. **`mutter-scan`**) or the same skill names · Codex / OpenCode → plugin / skill UI. **CLI** = `python3 scripts/mutter.py …` from **repo root** (after **bootstrap** installed the script).\n\n### 0 — First time\n\n1. **`/mutter:bootstrap`** — `.mutter/`, entry files, `scripts/mutter.py` if missing\n2. **`/mutter:scan`** — `metadata/scan-state.json` + `index/` shards\n3. Optional: **`python3 scripts/mutter.py agent-cadence --out .mutter/context/agent-cadence.md`** — when to run which skill vs CLI\n4. Optional (product / application repos): **`python3 scripts/mutter.py prd-init`**, then **`python3 scripts/mutter.py validate-prd`** — canonical **`.mutter/prd/PRD.md`** (see **Direction** under step 2 below)\n\n### 1 — New session (resume cheaply)\n\n1. **`python3 scripts/mutter.py status`** — `active_task` / `active_plan` in `.mutter/state/current.json`\n2. **`python3 scripts/mutter.py context-pack --out .mutter/context/session-pack.md`**\n3. Before heavy work: **`python3 scripts/mutter.py preflight --require-active-task --check-acceptance-verify`** (add **`--require-plan-for-large`** for big / risky diffs)\n\n### 2 — Direction (before locking scope)\n\n- **`/mutter:prd`** — workspace **Product Requirements Document** at **`.mutter/prd/PRD.md`** (product “what / why” for agents). First time: **`python3 scripts/mutter.py prd-init`**; after edits: **`python3 scripts/mutter.py validate-prd`**. Distinct from repo-root **`SPEC.md`** when your repo is **Mutter itself** — **`SPEC.md`** describes the framework; **`PRD.md`** describes *your* product in a consumer workspace.\n- **`/mutter:brainstore`** — notes / spikes → `.mutter/brainstore/`\n- **`/mutter:architecture`** — boundaries, APIs, ADRs; after ADR edits → **`python3 scripts/mutter.py validate-adr`**\n- **`/mutter:roadmap`** — themes, milestones, debt. With **empty** args: align roadmap with architecture, then **`/mutter:task create`** (no title) can spawn tasks from open roadmap items\n\n### 3 — PRD vs roadmap vs plan\n\n- **PRD** (optional but recommended for app/product work) = stable **product intent**: goals, users, problems, functional scope — **`.mutter/prd/PRD.md`**. **`context-pack`** includes a PRD excerpt when that file exists.\n- **Roadmap** = *what* over time (outcomes, milestones).\n- **Plan** = *how* for **one** scoped change → **`/mutter:plan`**, then **`python3 scripts/mutter.py validate-plan`**. Optional: **`python3 scripts/mutter.py risk-check --from-git`**.\n\n### 4 — Tasks (execute / continue)\n\n1. **`/mutter:task create \"…\"`** — one **Steps** checkbox ≈ one agent turn (one **Read:** list, one outcome); **`split`** if a step needs “the whole repo”. Prefer **reuse** of existing modules/helpers (see **task** skill and **`TASK.md`** template). If no explicit task file, follow the **task** skill: check **`.mutter/plans/`**, **`.mutter/roadmap/`**, optionally **`.mutter/prd/PRD.md`**, **`.mutter/state/current.json`**\n2. Set **`active_task`** in **`.mutter/state/current.json`** when executing (per **task** skill)\n3. Per step: **`/mutter:safe-edit`** (or same discipline) → tick **one** step → append **`.mutter/logs/tasks.log`** → **`python3 scripts/mutter.py sync-task-progress`** → **`/mutter:status`** or **`python3 scripts/mutter.py tasks-status --task `**\n4. **Session context:** After a step is **fully** done (not mid-step), check your harness’s context meter. If it’s **~40% or higher**, the default recommendation is a **new chat**, then **`context-pack`** and **`status`**, then the next **Steps** line — see **`/mutter:task`** and **`agent-cadence`**. Staying in the same thread is fine if you explicitly choose it.\n5. Before “done”: **`python3 scripts/mutter.py validate-task`**\n\n### 5 — After code lands\n\n- **`/mutter:scan`** when meaningful code changed\n\n### 6 — Before PR / merge\n\n1. **`/mutter:review-diff`** → findings under **`.mutter/reviews/`**; fix **Critical** before merge\n2. **`python3 scripts/mutter.py suggest-tests --from-git`**, **`scan-secrets`**, **`validate-task`** / **`validate-tasks`** as needed\n3. **`python3 scripts/mutter.py pr-template`**\n\n### 7 — Ship\n\n- CI: **`validate-tasks`**, **`validate-plans`**, optional **`guard-large-change`**\n- **`python3 scripts/mutter.py report-change`** for release notes / handoff\n\n**Regenerate cheat sheet anytime:** **`python3 scripts/mutter.py agent-cadence`**. Workspace tools detail: [`docs/mutter-workspace-tools-audit.md`](docs/mutter-workspace-tools-audit.md).\n\n### Token habits (same ideas as [`.mutter/core/project.md`](.mutter/core/project.md))\n\n- **Disk coordinates** — scope, checklists, `execution_progress` live in `.mutter/` so new sessions do not replay the whole story in chat.\n- **One-window steps** — explicit paths + index keys per step; **`split`** or **`workers`** if too wide.\n- **context-pack** over ad-hoc multi-file pastes; pair with the **task** skill’s **~40% checkpoint** when a long session gets heavy.\n- **Logs off-transcript** — long output → **`.mutter/logs/`**; in chat: exit code, a few lines, path.\n- **Official docs** — before web search, open **one** section of **`memory/official-tech-docs-roadmap.md`** if your project maintains it.\n\n---\n\n## Skills (most used first)\n\nClaude: **`/mutter:`** · Cursor: same names + palette · Codex: plugin UI · OpenCode: skill tool.\n\n| Skill | When | What |\n|-------|------|------|\n| **bootstrap** | No `.mutter/` or upgrade | Template; **`bootstrap-sync`** refreshes shipped files without wiping tasks/plans/architecture. |\n| **scan** | After real code change | Incremental scan, indexes, `scan-state`. |\n| **task** | Work on disk | **create** / **update** / **split** / **execute**; one **Steps** box per turn; **`sync-task-progress`** after each tick; **~40% session checkpoint** after each finished step (new session + **`context-pack`** when high); bare **task** = current queue. |\n| **status** | Progress | With **`tasks-status`**. |\n| **plan** | Multi-file or risky change | Scoped plan + verify; then **`validate-plan`**. |\n| **safe-edit** | Any edit | Explain → minimal diff → narrow verify; long output → **`.mutter/logs/`**. |\n| **review-diff** | Pre-merge | Quality, security, tests; severity tags → **`.mutter/reviews/`**. |\n| **brainstore** | Ideas / intel | **`.mutter/brainstore/`** — use early to keep chat small. |\n| **prd** | Product spec for agents | **`.mutter/prd/PRD.md`** — **`prd-init`**, **`validate-prd`**; revise when roadmap/architecture changes product scope. |\n| **roadmap** | Direction over time | **`.mutter/roadmap/`**; empty args → align with **architecture** before new tasks. |\n| **architecture** | Boundaries / ADRs | Design truth; **`validate-adr`** when ADRs change. |\n| **workers** | Epics / parallelism | Queue + briefs + file caps; after **split** if still too wide. |\n| **context** | Tight bundles | **`.mutter/context/`** + **`context-pack`**. |\n| **memory** | Long-lived conventions | Includes **`official-tech-docs-roadmap.md`**. |\n| **workflow** | Repeatable process | Files under **`.mutter/workflows/`**. |\n| **snapshot** | Checkpoint | Index / architecture / roadmap snapshot. |\n| **help** | Orientation | Index of commands / rules. |\n| **explain** | Understand code | Minimal reads. |\n| **analyze** | Deeper dive | Needs explicit file list. |\n| **risks** | Change assessment | Risk register. |\n| **dependencies** | Graph | Dependency slice. |\n| **tests** | Coverage mapping | Tests vs changes. |\n| **affected** | Blast radius | Affected files / domains. |\n| **review** | Extra pass | Structured review wrapper. |\n\n---\n\n## Cursor palette (`mutter-cursor/commands/`)\n\nMarkdown-backed commands (**`mutter-`**). Common governance / validation:\n\n| Command | Use |\n|---------|-----|\n| **mutter-agent-cadence** | Skill vs CLI cadence (`agent-cadence`). |\n| **mutter-preflight** | State, dirty git, diff size, etc. |\n| **mutter-status** | Checklist table (`tasks-status`). |\n| **mutter-context-pack** | Session Markdown bundle. |\n| **mutter-prd** | PRD workflow (`prd` skill); pairs with **`prd-init`** / **`validate-prd`**. |\n| **mutter-validate** | Task / plan validation via workspace CLI. |\n| **mutter-governance** | ADRs, boundaries, quality gates. |\n\nOther `*.md` files mirror skills (scan, plan, task, prd, …).\n\n---\n\n## Workspace CLI\n\nPrimary entry point: **`scripts/mutter.py`** (run from repo root after **bootstrap**).\n\n**Requirements:** Python 3 (stdlib for most commands). YAML boundaries may need **PyYAML** — see `.mutter/core/project.md` and `boundaries.json`.\n\nResolves repo root by walking up for **`.mutter/`**, or pass **`--root`**. In consumer repos the file usually comes from **bootstrap** (`mutter-claude/templates/scripts/mutter.py` → `/scripts/mutter.py`).\n\n| Command | When | What |\n|---------|------|------|\n| `agent-cadence` | Start / onboarding | Phases → skills → CLI; `--out .mutter/context/agent-cadence.md` |\n| `status` | Each new session | `.mutter/state/current.json` + active task/plan snippets |\n| `preflight` | Before large / risky work | State, optional active task, dirty git, diff size |\n| `context-pack` | Cold start / handoff | Markdown pack (task, plan, **PRD excerpt** if present); `--out` |\n| `tasks-status` | After task steps | Table; `--task` for one file |\n| `sync-task-progress` | After checkbox ticks | `execution_progress` in `.mutter/state/current.json` |\n| `validate-task` | Before task “done” | One task (default: active) |\n| `validate-tasks` | CI / release | Tasks in selected buckets |\n| `validate-plan` | After a plan | One file under `.mutter/plans/` |\n| `validate-plans` | CI | All plans |\n| `prd-init` | First PRD | Create `.mutter/prd/PRD.md` from template (`--force` overwrites) |\n| `validate-prd` | After PRD edits | Structure check (default: `.mutter/prd/PRD.md`; `--prd` path) |\n| `suggest-tests` | Before PR | Commands from `.mutter/testing/commands.json` |\n| `pr-template` | Open PR | Body from task/plan + git + suggested tests |\n| `scan-state` | After scan | `changed_files` from `metadata/scan-state.json` |\n| `risk-check` | Around a change | LOW/MEDIUM/HIGH heuristics (git or scan-state) |\n| `scan-secrets` | Before merge | Best-effort local secret patterns |\n| `report-change` | Release notes | Markdown skeleton |\n| `bootstrap-sync` | Plugin upgrade | Refresh template-managed `.mutter/` + `mutter.py` |\n| `check-boundaries` | Architecture | From `.mutter/boundaries.json` |\n| `validate-migrations` | DB migrations | Rollback / backup notes when paths change |\n| `validate-adr` | ADR edits | `.mutter/adr/*.md` structure |\n| `validate-quality-gate` | By work type | `quality-gates/.md` exists |\n| `scan-todos` | Tech debt | TODO/FIXME → `metadata/todos.json` |\n| `guard-large-change` | Large PRs | Thresholds / critical paths need plan |\n| `check-skill-refs` | Mutter dev | Relative `.md` links in skills |\n| `ci` | This repo’s CI | Refs + tasks + plans + optional Cursor skill sync |\n\n```bash\npython3 scripts/mutter.py --help\n```\n\n**Optional hook:** `git config core.hooksPath scripts/git-hooks` (when `.mutter/` and `scripts/mutter.py` exist).\n\n**Cursor ↔ Claude skill sync (Mutter development):** `python3 scripts/sync_cursor_skills.py` — `ci` with **`--check-cursor-sync`** requires `mutter-cursor/skills` to match `mutter-claude/skills`.\n\n---\n\n## `.mutter/` layout\n\nCanonical map: [`.mutter/core/project.md`](.mutter/core/project.md) — `index/`, `architecture/`, `tasks/`, `plans/`, **`prd/`**, `state/`, `workflows/`, `memory/`, `logs/`, `brainstore/`, etc. **Incremental shards**, not one giant file.\n\n---\n\n## Community\n\n- **Author:** [Ventsislav Arnaudov](https://varnaudov.com)\n- **Repo:** [github.com/arnaudovproject/mutter](https://github.com/arnaudovproject/mutter)\n- **Issues:** [GitHub Issues](https://github.com/arnaudovproject/mutter/issues)\n\nSimilar **idea space** to [Superpowers](https://github.com/obra/superpowers) (skills encode **process**; filesystem coordinates). Mutter is its own product: `.mutter/` indexes, tasks, plans, and parity across Claude, Cursor, Codex, and OpenCode.\n\n---\n\n## License\n\nMIT — see `package.json` and manifests under `mutter-claude/` and `mutter-cursor/`.\n",
"bytes": 21541,
"sha": "8413b6f8e9165633211ad53c46ca131a5e93859ea5c8da4d81e4787235929a6b",
"repo_slug": "arnaudovproject/mutter",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_arnaudovproject_mutter_mutter_3d11efd7/readme"
}
![\"Mutter\"](\"docs/logo.png\"){kind=logo}
\n