Mutter
Quick install (Claude Code)
Register the repository root (the folder that contains .claude-plugin/marketplace.json), not mutter-claude/:
/plugin marketplace add /path/to/mutter
/plugin install mutter@mutter-plugins
/reload-plugins
Verify with /mutter:help.
Do not install Mutter by symlinking into ~/.claude/plugins. It is a Claude marketplace plugin: add the repo with /plugin marketplace add, then install mutter@mutter-plugins as above.
Mutter is a plugin and methodology for an AI workspace on top of your code: structured on-disk memory (.mutter/), token-efficient workflows, tasks, plans, incremental indexing, and consistent operating rules across several agent harnesses.
The plugin name in manifests is mutter (lowercase). In Claude Code, skills are invoked under the /mutter:<name> namespace — for example /mutter:scan, /mutter:help (docs sometimes shorten this to “/mutter scan”; in Claude Code the colon form is canonical).
What Mutter does
| Area | Description |
|---|
| Project memory | The .mutter/ tree — architecture, tasks, plans, indexes, logs, rules — without dumping monolithic blobs into chat. |
| Navigation | Index shards and explicit paths first; the whole repository is not loaded into context. |
| Orchestration | Scanning, task, plan, parallel workers, safe-edit, and review-diff. |
| Discipline | Small entry files (CLAUDE.md, Cursor rules); detail lives under .mutter/. |
| Tooling | Optional Python CLI scripts/mutter.py for validation, preflight, context packing, CI checks, and more. |
Who it is for: teams and large codebases where you want agents to follow one process, resume state between sessions, and use fewer tokens for the same accuracy.
Full product spec: SPEC.md. Harness and plugin development reference: docs/mutter-plugin-harness-reference.md.
Supported agents and where the code lives
| Agent | Package / path in this repo |
|---|
| Claude Code | mutter-claude/ (.claude-plugin/plugin.json) |
| OpenAI Codex | Same skills as Claude — manifest at mutter-claude/.codex-plugin/plugin.json |
| Cursor | mutter-cursor/ (rules, skills, palette commands) |
| OpenCode | Repo root: package.json + .opencode/plugins/mutter.js (registers mutter-claude/skills) |
Codex and Claude share the same Markdown skills under mutter-claude/skills/. Cursor keeps a synchronized copy under mutter-cursor/skills/ (refreshed by a script during development).
Installation
Claude Code
Global install: use Quick install (Claude Code) at the top of this README (/plugin marketplace add → /plugin install mutter@mutter-plugins → /reload-plugins).
- Clone (if you do not have the repo yet):
git clone https://github.com/arnaudovproject/mutter.git
- Marketplace path — pass the clone root. Example: if the repo is at
/code/claude/mutter/mutter, run /plugin marketplace add /code/claude/mutter/mutter. Claude registers the catalog from .claude-plugin/marketplace.json (name mutter-plugins); the plugin package lives under mutter-claude/ and installs as mutter@mutter-plugins.
- Update —
git pull in the clone, then /reload-plugins in Claude Code.
- Uninstall —
/plugin uninstall mutter, then /plugin marketplace remove mutter-plugins.
Local / dev (run from a clone without marketplace): from the repo root, claude --plugin-dir ./mutter-claude. After editing plugin files: /reload-plugins.
Official docs: Plugins · Plugins reference.
Cursor
- Marketplace / team catalog: import the Git repo as a team marketplace (e.g. Dashboard → Plugins → Team Marketplaces → Import). At the repo root,
.cursor-plugin/marketplace.json points at ./mutter-cursor for the mutter plugin.
- Local development install: copy or symlink the plugin tree so
mutter-cursor/.cursor-plugin/plugin.json sits at the root of the installed plugin, for example:
ln -s /path/to/mutter/mutter-cursor ~/.cursor/plugins/local/mutter
Then in Cursor: Developer: Reload Window.
Documentation: Cursor Plugins · Plugins reference.
