# Muse

**Git tracks lines of text. Muse tracks anything.**

Version control built for the age of agents — where the state you care about is multidimensional, the collaborators are often non-human, and a line-diff is the wrong unit of thought.

[![Python 3.14](https://img.shields.io/badge/python-3.14-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

---

The version control systems we have were designed for one thing: tracking changes to lines of text. That model has held up remarkably well. It just wasn't designed for MIDI tracks with 21 independent dimensions, or codebases where the meaningful unit is a symbol, not a line, or scientific simulations where state is a tensor, or any domain where multiple axes of change need to be reasoned about independently.

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 — is domain-agnostic. Your domain is a plugin: six methods. Implement those and you immediately get 40+ CLI commands, agent-ready JSON output, CRDT multi-agent convergence, and a remote hosting layer via [MuseHub](https://localhost:1337).

---

## Quickstart

```bash
pip install -e ".[dev]"

muse init --domain code          # or midi, or your own plugin
muse status                      # drift vs HEAD
muse diff                        # typed delta by dimension
muse commit -m "feat: add core"  # snapshot with full provenance
muse log --format json           # pipe to anything
muse branch feat/refactor        # branch like you always have
muse merge feat/refactor         # three-way merge — per dimension
muse push local main             # push to MuseHub
```

No database. No daemon. All state in `.muse/` — same mental model as `.git/`, better semantics.

---

## What makes it different

| | Git | Muse |
|---|---|---|
| Unit of state | Line of text | Typed snapshot of any state space |
| Diff | Additions / deletions | Typed delta per domain dimension |
| Merge | Line-level | Three-way per dimension — independent axes never conflict |
| Domain | Hard-coded (files + text) | Plugin protocol — six methods |
| Agent support | None | `--json` on every command; CRDT mode for zero-conflict multi-agent writes |

**Code domain:** Two agents edit 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. The merge auto-succeeds. The rename is detected and propagated.

**MIDI domain:** Two agents edit the same MIDI file — one edits sustain pedal data, the other edits pitch bend. Both touch the same file. In Git, that's a conflict. In Muse, those are independent dimensions. The merge always succeeds. No human required.

---

## Install

```bash
curl -fsSL https://localhost:1337/install.sh | sh
```

**Subsequent updates** — once muse is installed, it manages itself:

```bash
muse pull local main
```

**Requirements:**
- Python 3.14+
- `mido` — for the MIDI domain
- `tree-sitter` + language grammars — for the Code domain

---

## The plugin contract

Six methods. That's the entire surface area for a new domain.

```python
class MuseDomainPlugin(Protocol):
    def snapshot(self, live_state: LiveState) -> StateSnapshot: ...
    def diff(self, base: StateSnapshot, target: StateSnapshot, ...) -> StateDelta: ...
    def merge(self, base, left, right, ...) -> MergeResult: ...
    def drift(self, committed: StateSnapshot, live: LiveState) -> DriftReport: ...
    def apply(self, delta: StateDelta, live: LiveState) -> LiveState: ...
    def schema(self) -> DomainSchema: ...
```

Implement those six and you get branching, three-way merge, content-addressed object storage, commit history, reflog, cherry-pick, revert, bisect, shelf, tags, worktrees, garbage collection, archive export, offline bundles, and 40+ CLI commands — all immediately working, all domain-agnostic.

Two optional extensions unlock richer semantics:

- **`StructuredMergePlugin`** — sub-snapshot auto-merge via Operational Transformation
- **`CRDTPlugin`** — convergent multi-agent writes; `muse merge` always succeeds, no conflict state ever

---

## Shipped domains

### Code *(default)*
Code as a **graph of named symbols** — not a bag of 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 operations that are strictly impossible in Git. Supported languages: Python, TypeScript, JavaScript, Go, Rust, Java, C, C++, C#, Ruby, Kotlin.

### MIDI *(reference implementation)*
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.

### Planned
Genomics · Scientific simulation · 3D spatial design · Spacetime simulation

---

## Built for agents

Every command emits `--json`. Every exit code is stable and documented. The CLI is fully synchronous — no background daemons, no event loops, no surprises. Agents get the same interface humans do, with richer machine-readable output.

```bash
muse status --json
muse log --format json | jq '.[0].commit_id'
muse commit -m "checkpoint" --agent-id worker-3 --model-id claude-sonnet-4-6 --sign
muse coord reserve "file.py::MyClass" --ttl 300   # multi-agent symbol locking
```

[Plumbing reference →](docs/reference/plumbing.md) · [Porcelain reference →](docs/reference/porcelain.md)

---

## Documentation

| | |
|---|---|
| [Porcelain reference](docs/reference/porcelain.md) | All 30+ high-level commands — flags, JSON schemas, conflict flows |
| [Plumbing reference](docs/reference/plumbing.md) | All 22 low-level commands — flags, JSON schemas, composability patterns |
| [Plugin authoring guide](docs/guide/plugin-authoring-guide.md) | Step-by-step: build and ship a new domain in under an hour |
| [Architecture](docs/architecture/muse-vcs.md) | Full technical design, module map, layer rules |
| [CRDT reference](docs/guide/crdt-reference.md) | VectorClock, LWWRegister, ORSet, RGA, AWMap, GCounter |
| [Plugin protocol](docs/protocol/muse-protocol.md) | Language-agnostic `MuseDomainPlugin` spec |
| [Type contracts](docs/reference/type-contracts.md) | Every named type with field tables |
| [`.museattributes`](docs/reference/muse-attributes.md) | Per-path merge strategy overrides |
| [`.museignore`](docs/reference/museignore.md) | Snapshot exclusion rules |

---

*v0.1.4 · Python 3.14 · MIT License*

testing stuff