README.md
markdown
| 1 | # Muse |
| 2 | |
| 3 | **Git tracks lines of text. Muse tracks anything.** |
| 4 | |
| 5 | Version control for multidimensional state — music, code, genomics, 3D design, scientific simulation. One engine. Any domain. Agents as first-class citizens. |
| 6 | |
| 7 | [](https://github.com/cgcardona/muse/actions) |
| 8 | [](https://python.org) |
| 9 | [](LICENSE) |
| 10 | |
| 11 | --- |
| 12 | |
| 13 | ## The idea in one paragraph |
| 14 | |
| 15 | Git works because text is one-dimensional — a sequence of lines. Diffs are additions and deletions to that sequence. The moment your state has multiple independent axes — 21 MIDI dimensions, a graph of AST symbols, a climate model grid — Git becomes meaningless. Muse replaces the line-diff model with a **typed delta algebra** over any state space you define. The core engine (DAG, branching, three-way merge, content-addressed object store) never changes. Your domain is a plugin — six methods — and Muse handles the rest. |
| 16 | |
| 17 | --- |
| 18 | |
| 19 | ## Live Demos |
| 20 | |
| 21 | Two domains, fully interactive: |
| 22 | |
| 23 | **→ [MIDI Demo](https://cgcardona.github.io/muse/)** — version control for music. Commit DAG, DAW track view, 21-dimension heatmap, note-level merge with zero conflicts between dimensions. |
| 24 | |
| 25 | **→ [Code Demo](https://cgcardona.github.io/muse/)** — version control for code graphs. Symbol-level diff, AST-aware merge, hotspot detection, rename and move tracking — across 11 languages. |
| 26 | |
| 27 | --- |
| 28 | |
| 29 | ## Install |
| 30 | |
| 31 | ```bash |
| 32 | git clone https://github.com/cgcardona/muse |
| 33 | cd muse |
| 34 | pip install -e ".[dev]" |
| 35 | ``` |
| 36 | |
| 37 | No database. No daemon. All state lives in `.muse/` — same mental model as `.git/`. |
| 38 | |
| 39 | --- |
| 40 | |
| 41 | ## Quick start |
| 42 | |
| 43 | ```bash |
| 44 | muse init --domain midi # init a repo (midi, code, or your own plugin) |
| 45 | muse commit -m "Add verse" # snapshot the working tree |
| 46 | muse checkout -c feat/chorus # branch |
| 47 | muse status # drift vs HEAD |
| 48 | muse diff # what changed, typed by dimension |
| 49 | muse merge feat/chorus # three-way merge — conflicts are real domain conflicts |
| 50 | muse log --format json # pipe to anything; every command is agent-ready |
| 51 | ``` |
| 52 | |
| 53 | That's it. Everything else is flags. |
| 54 | |
| 55 | --- |
| 56 | |
| 57 | ## What makes it different |
| 58 | |
| 59 | | | Git | Muse | |
| 60 | |---|---|---| |
| 61 | | Unit of state | Line of text | Snapshot of any typed state space | |
| 62 | | Diff | Line additions / deletions | Typed delta per domain dimension | |
| 63 | | Merge | Line-level | Three-way per dimension — independent axes never conflict | |
| 64 | | Domain | Hard-coded (files + text) | Plugin protocol — six methods | |
| 65 | | Agent support | None | JSON output on every command; CRDT mode for zero-conflict multi-agent writes | |
| 66 | |
| 67 | **MIDI example:** Two agents edit the same MIDI file — one changes sustain pedal data, the other changes pitch bend. In Git, both touch the same file, so they conflict. In Muse, sustain and pitch bend are independent dimensions. The merge always succeeds. No human in the loop. |
| 68 | |
| 69 | **Code example:** Two agents refactor the same file — one renames a function, the other adds a parameter to a different function. Muse tracks symbols by content hash, not line number. No conflict. The rename is detected and propagated automatically. |
| 70 | |
| 71 | --- |
| 72 | |
| 73 | ## The plugin contract |
| 74 | |
| 75 | Six methods. That's the entire API surface for a new domain. |
| 76 | |
| 77 | ```python |
| 78 | class MuseDomainPlugin(Protocol): |
| 79 | def snapshot(self, live_state: LiveState) -> StateSnapshot: ... |
| 80 | def diff(self, base: StateSnapshot, target: StateSnapshot, ...) -> StateDelta: ... |
| 81 | def merge(self, base, left, right, ...) -> MergeResult: ... |
| 82 | def drift(self, committed: StateSnapshot, live: LiveState) -> DriftReport: ... |
| 83 | def apply(self, delta: StateDelta, live: LiveState) -> LiveState: ... |
| 84 | def schema(self) -> DomainSchema: ... |
| 85 | ``` |
| 86 | |
| 87 | Implement those six and you get branching, three-way merge, a content-addressed object store, commit history, reflog, cherry-pick, revert, bisect, stash, tags, worktrees, garbage collection, archive export, offline bundles, and 40+ CLI commands — all domain-agnostic, all immediately working. |
| 88 | |
| 89 | Two optional extensions unlock richer semantics: |
| 90 | |
| 91 | - **`StructuredMergePlugin`** — sub-file auto-merge via Operational Transformation |
| 92 | - **`CRDTPlugin`** — convergent multi-agent writes; `muse merge` always succeeds, no conflict state ever |
| 93 | |
| 94 | --- |
| 95 | |
| 96 | ## Shipped domains |
| 97 | |
| 98 | ### MIDI *(reference implementation)* |
| 99 | State across **21 independent dimensions**: notes, pitch bend, polyphonic aftertouch, 11 CC controllers, program changes, tempo map, time signatures, key signatures, markers, track structure. Note-level Myers LCS diff. Dimension-aware three-way merge. Voice-aware RGA CRDT. MIDI query DSL. 31 semantic porcelain commands. |
| 100 | |
| 101 | ### Code *(second domain)* |
| 102 | Code as a **graph of named symbols** — not a bag of text lines. Symbol-level diff. AST-aware merge. Rename and move detection via content-addressed symbol identity. Two agents editing different functions in the same file always auto-merge. 12 commands strictly impossible in Git. Supported languages: Python, TypeScript, JavaScript, Go, Rust, Java, C, C++, C#, Ruby, Kotlin. |
| 103 | |
| 104 | ### Planned |
| 105 | Genomics · Scientific Simulation · 3D Spatial Design · Spacetime Simulation |
| 106 | |
| 107 | --- |
| 108 | |
| 109 | ## For agents |
| 110 | |
| 111 | Every porcelain and plumbing command emits `--format json`. Every exit code is stable and documented. The entire CLI is synchronous — no background daemons, no event loops, no surprises. |
| 112 | |
| 113 | ```bash |
| 114 | # Machine-readable output everywhere |
| 115 | muse status --json |
| 116 | muse log --format json | jq '.[0].commit_id' |
| 117 | muse commit -m "agent checkpoint" --format json | jq .snapshot_id |
| 118 | |
| 119 | # Full plumbing layer for agent pipelines |
| 120 | muse plumbing rev-parse HEAD -f text |
| 121 | muse plumbing commit-graph --tip main -f json |
| 122 | muse plumbing pack-objects HEAD | muse plumbing unpack-objects |
| 123 | ``` |
| 124 | |
| 125 | [Plumbing reference →](docs/reference/plumbing.md) · [Porcelain reference →](docs/reference/porcelain.md) |
| 126 | |
| 127 | --- |
| 128 | |
| 129 | ## Documentation |
| 130 | |
| 131 | | | | |
| 132 | |---|---| |
| 133 | | [Plumbing reference](docs/reference/plumbing.md) | All 22 low-level commands — flags, JSON schemas, exit codes, composability patterns | |
| 134 | | [Porcelain reference](docs/reference/porcelain.md) | All 30+ high-level commands — flags, JSON schemas, conflict flows | |
| 135 | | [Plugin authoring guide](docs/guide/plugin-authoring-guide.md) | Step-by-step: build and ship a new domain in under an hour | |
| 136 | | [Architecture](docs/architecture/muse-vcs.md) | Full technical design, module map, layer rules | |
| 137 | | [CRDT reference](docs/guide/crdt-reference.md) | VectorClock, LWWRegister, ORSet, RGA, AWMap, GCounter — API and lattice laws | |
| 138 | | [Plugin protocol](docs/protocol/muse-protocol.md) | Language-agnostic `MuseDomainPlugin` spec | |
| 139 | | [Type contracts](docs/reference/type-contracts.md) | Every named type with field tables | |
| 140 | | [`.museattributes`](docs/reference/muse-attributes.md) | Per-path merge strategy overrides | |
| 141 | | [`.museignore`](docs/reference/museignore.md) | Snapshot exclusion rules | |
| 142 | |
| 143 | --- |
| 144 | |
| 145 | ## Requirements |
| 146 | |
| 147 | - Python 3.14+ |
| 148 | - `mido` (MIDI plugin) |
| 149 | - `tree-sitter` + language grammars (Code plugin) |
| 150 | |
| 151 | --- |
| 152 | |
| 153 | *v0.1.4 · Python 3.14 · Built from the couch. March 2026.* |