docs/demo/demo-code.md · cgcardona/muse

1

# Muse Code Plugin — Tour de Force

2

3

> **The question is not "why would you use Muse instead of Git?"**

4

> **The question is: "how did you ever live without this?"**

5

6

This is a walk-through of every code-domain capability in Muse — 12 commands

7

that treat your codebase as what it actually is: a **typed, content-addressed

8

graph of named, versioned symbols**. Not lines. Not files. Symbols.

9

10

Every command below is strictly impossible in Git. Read on.

---

## Setup

```bash

muse init --domain code

18

echo "class Invoice: ..." > src/billing.py

19

muse commit -m "Add billing module"

20

# ... several more commits ...

```

---

## Act I — What's in the Snapshot?

26

27

### `muse symbols` — see every named thing

```

$ muse symbols

src/billing.py

class Invoice line 4

method Invoice.__init__ line 8

35

method Invoice.compute_total line 18

36

method Invoice.apply_discount line 25

37

38

src/auth.py

39

class AuthService line 3

40

method AuthService.validate_token line 11

41

function generate_token line 28

42

43

src/utils.py

44

function retry line 2

45

function sha256_bytes line 12

3 files, 9 symbols

```

**Why Git can't do this:** `git ls-files` gives you filenames. `muse symbols`

51

gives you the semantic inventory — functions, classes, methods — extracted from

52

actual ASTs across 10 languages (Python, TypeScript, JavaScript, Go, Rust, Java,

53

C, C++, C#, Ruby, Kotlin).

---

## Act II — Grep the Symbol Graph

58

59

### `muse grep` — semantic symbol search

60

61

```

62

$ muse grep "validate"

63

64

src/auth.py::AuthService.validate_token method line 11

65

src/billing.py::validate_amount function line 34

66

67

2 match(es) across 2 file(s)

```

```

$ muse grep "^Invoice" --kind class --regex

72

73

src/billing.py::Invoice class line 4

74

75

1 match(es) across 1 file(s)

```

```

$ muse grep "handle" --language Go

80

81

api/server.go::Server.HandleRequest method line 12

82

api/server.go::handleError function line 28

83

84

2 match(es) across 1 file(s)

85

```

86

87

**Why Git can't do this:** `git grep "validate"` searches raw text lines. It

88

finds every comment, every string literal, every `# validate_token is deprecated`

89

in your codebase. `muse grep` searches the *typed symbol graph* — only actual

90

symbol declarations, with their kind, language, and stable identity hash. Zero

false positives.

---

## Act III — Query the Symbol Graph

96

97

### `muse query` — SQL for your codebase

98

99

```

100

$ muse query "kind=function" "language=Python" "name~=validate"

101

102

src/billing.py::validate_amount fn line 34

103

src/auth.py::validate_token fn line 11

104

105

2 match(es) across 2 file(s) [kind=function AND language=Python AND name~=validate]

```

```

$ muse query "kind=method" "name^=__"

110

111

src/billing.py::Invoice.__init__ method line 8

112

src/models.py::User.__init__ method line 9

113

src/models.py::User.__repr__ method line 24

114

115

3 match(es) across 2 file(s) [kind=method AND name^=__]

```

```

$ muse query "hash=a3f2c9" --hashes

120

121

src/billing.py::validate_amount fn line 34 a3f2c9..

122

src/payments.py::validate_payment fn line 7 a3f2c9..

123

124

2 match(es) across 2 file(s) [hash=a3f2c9]

125

```

126

127

**The `hash` predicate is uniquely powerful.** `muse query "hash=a3f2c9"` finds

128

every symbol across your entire repo whose normalized AST is byte-for-byte

129

identical to the one with that hash prefix. Copy detection. Duplication

130

tracking. Cross-module clone detection. This has no analogue anywhere in

131

Git's model — or any other VCS.

132

133

Predicate operators: `=` (exact), `~=` (contains), `^=` (starts with), `$=` (ends with).

134

Predicate keys: `kind`, `language`, `name`, `file`, `hash`.

---

## Act IV — Language Breakdown

139

140

### `muse languages` — composition at a glance

```

$ muse languages

Language breakdown — commit cb4afaed

146

147

Python 8 files 43 symbols (fn: 18, class: 5, method: 20)

148

TypeScript 3 files 12 symbols (fn: 4, class: 3, method: 5)

149

Go 2 files 8 symbols (fn: 6, method: 2)

150

Rust 1 file 4 symbols (fn: 2, method: 2)

151

────────────────────────────────────────────────────────────────────

152

Total 14 files 67 symbols (4 languages)

153

```

154

155

One command. Instant polyglot codebase inventory. No scripts, no cloc,

no custom tooling.

---

## Act V — Who Changed What?

161

162

### `muse blame` — per-symbol attribution

163

164

```

165

$ muse blame "src/billing.py::Invoice.compute_total"

166

167

src/billing.py::Invoice.compute_total

168

──────────────────────────────────────────────────────────────

169

last touched: cb4afaed 2026-03-16

170

author: alice

171

message: "Perf: optimise compute_total with vectorisation"

172

change: implementation changed

173

174

previous: 1d2e3faa 2026-03-15

175

change: renamed from calculate_total

176

177

before that: a3f2c9e1 2026-03-14

change: created

```

**Why Git can't do this:** `git blame src/billing.py` gives you 300 attribution

182

entries for a 300-line file — one per line, including blank lines, docstrings,

183

and closing braces. `muse blame` gives you **one answer per function**: this

184

commit, this author, this specific kind of change. That's the level of

185

precision code review actually needs.

---

## Act VI — Symbol History

190

191

### `muse symbol-log` — the life of a function

192

193

```

194

$ muse symbol-log "src/billing.py::Invoice.compute_total"

195

196

Symbol timeline: src/billing.py::Invoice.compute_total

197

198

cb4afaed 2026-03-16 implementation changed "Perf: optimise..."

199

1d2e3faa 2026-03-15 renamed from calculate_total "Refactor billing API"

200

a3f2c9e1 2026-03-14 created "Add billing module"

201

202

3 events tracked across 3 commits

203

```

204

205

`muse symbol-log` follows renames and cross-file moves automatically.

206

If `compute_total` was called `calculate_total` last week, you get the

207

full continuous history — not the truncated stub that `git log -- src/billing.py`

208

would give you after a rename.

---

## Act VII — Detect Refactoring

213

214

### `muse detect-refactor` — classify semantic changes

215

216

```

217

$ muse detect-refactor HEAD~5..HEAD

218

219

Semantic refactoring — HEAD~5..HEAD

220

Commits analysed: 5

221

222

rename src/billing.py::calculate_total → compute_total (cb4afaed)

223

rename src/billing.py::apply_tax → apply_vat (cb4afaed)

224

move src/billing.py::validate_amount → src/validation.py (1d2e3faa)

225

signature src/auth.py::AuthService.login signature changed (a3f2c9e1)

226

227

4 refactoring operations across 3 commits

228

```

229

230

**Why Git can't do this:** Git knows nothing about renames at the function

231

level. It might guess at file renames if the diff is similar enough.

232

`muse detect-refactor` reads the structured delta stored in every commit

233

and classifies operations with precision: rename, move, signature change,

234

implementation change. No guessing.

---

## Act VIII — Where is the Instability?

239

240

### `muse hotspots` — symbol churn leaderboard

241

242

```

243

$ muse hotspots --top 10

244

245

Symbol churn — top 10 most-changed symbols

246

Commits analysed: 47

247

248

1 src/billing.py::Invoice.compute_total 12 changes

249

2 src/api.py::handle_request 9 changes

250

3 src/auth.py::AuthService.validate_token 7 changes

251

4 src/models.py::User.save 5 changes

252

5 src/billing.py::Invoice.apply_discount 4 changes

253

254

High churn = instability signal. Consider refactoring or adding tests.

255

```

256

257

`muse hotspots` is the complexity map of your codebase. The functions that

258

change most are the ones most likely to harbour bugs, missing abstractions,

259

or untested edge cases. In a mature CI pipeline, this list drives test

260

coverage prioritisation.

261

262

```bash

263

# Scope to Python functions only, last 30 commits

264

muse hotspots --kind function --language Python --from HEAD~30 --top 5

265

```

266

267

**Why Git can't do this:** File-level churn (how many lines changed in

268

`billing.py`) misses the signal. A 1,000-line file might have 999 stable

269

lines and one function that burns. `muse hotspots` finds that function.

---

## Act IX — Where is the Bedrock?

274

275

### `muse stable` — symbol stability leaderboard

276

277

```

278

$ muse stable --top 10

279

280

Symbol stability — top 10 most stable symbols

281

Commits analysed: 47

282

283

1 src/core.py::sha256_bytes unchanged for 47 commits (since first commit)

284

2 src/core.py::content_hash unchanged for 43 commits

285

3 src/utils.py::retry unchanged for 38 commits

286

4 src/models.py::BaseModel.__init__ unchanged for 34 commits

287

288

These are your bedrock. High stability = safe to build on.

289

```

290

291

These are your load-bearing walls. New engineers can build on them.

292

Agents can call them without reading their implementation. If you're

293

designing a new feature, start here — find the stable primitives and

compose upward.

---

## Act X — Hidden Dependencies

299

300

### `muse coupling` — co-change analysis

301

302

```

303

$ muse coupling --top 10

304

305

File co-change analysis — top 10 most coupled pairs

306

Commits analysed: 47

307

308

1 src/billing.py ↔ src/models.py co-changed in 18 commits

309

2 src/api.py ↔ src/auth.py co-changed in 12 commits

310

3 src/billing.py ↔ tests/test_billing.py co-changed in 11 commits

311

4 src/models.py ↔ src/billing.py co-changed in 9 commits

312

313

High coupling = hidden dependency. Consider extracting a shared interface.

314

```

315

316

`billing.py` and `models.py` co-change in 18 out of 47 commits — 38% of

317

your commit history. There's no import between them that would reveal

318

this dependency to a static analyser. But Muse sees it in the commit

319

graph. Extract a `BillingProtocol` interface, define the contract explicitly,

320

and watch the coupling drop.

321

322

**Why Git can't do this cleanly:** A Git tool could count raw file

323

co-modifications. `muse coupling` counts *semantic* co-changes — commits

324

where both files had AST-level symbol modifications. Formatting-only

325

edits and non-code files are excluded. The signal is real.

---

## Act XI — Release Semantic Diff

330

331

### `muse compare` — any two historical snapshots

332

333

```

334

$ muse compare v1.0 v2.0

335

336

Semantic comparison

337

From: a3f2c9e1 "Release v1.0"

338

To: cb4afaed "Release v2.0"

339

340

src/billing.py

341

modified Invoice.compute_total (renamed from calculate_total)

342

modified Invoice.apply_discount (signature changed)

343

removed validate_amount (moved to src/validation.py)

344

345

src/validation.py (new file)

346

added validate_amount (moved from src/billing.py)

347

added validate_payment

348

349

api/server.go (new file)

350

added Server.HandleRequest

added handleError

added process

src/auth.py

modified AuthService.validate_token (implementation changed)

356

357

9 symbol change(s) across 4 file(s)

358

```

359

360

**This is the semantic changelog for your release** — automatically. No

361

manual writing, no diff archaeology. Every function that was added, removed,

362

renamed, moved, or modified between v1.0 and v2.0, classified and attributed.

363

364

`muse compare` reads both snapshots from the content-addressed object store,

365

parses their AST symbol trees, and diffs them. Any two refs — tags, branches,

366

commit IDs, relative refs (`HEAD~10`).

---

## Act XII — The Agent Interface

371

372

### `muse patch` — surgical semantic modification

373

374

This is where Muse becomes the version control system of the AI age.

375

376

```bash

377

$ cat new_compute_total.py

378

def compute_total(self, items: list[Item], tax_rate: Decimal = Decimal("0")) -> Decimal:

379

subtotal = sum(item.price * (1 - item.discount) for item in items)

380

return subtotal * (1 + tax_rate)

381

382

$ muse patch "src/billing.py::Invoice.compute_total" --body new_compute_total.py

383

384

✅ Patched src/billing.py::Invoice.compute_total

385

Lines 18–24 replaced (was 7 lines, now 3 lines)

386

Surrounding code untouched (8 symbols preserved)

387

Run `muse status` to review, then `muse commit`

388

```

389

390

**This is the paradigm shift for agents:**

391

392

An AI agent that needs to change `Invoice.compute_total` can do so with

393

surgical precision. It constructs a new function body, calls `muse patch`,

394

and the change is applied at the *symbol* level — not the line level, not

395

the file level. No risk of accidentally touching adjacent functions. No

396

diff noise. No merge required.

397

398

```bash

399

# Preview without writing

400

muse patch "src/billing.py::Invoice.compute_total" --body new_body.py --dry-run

401

402

# Apply from stdin — pipe directly from an AI agent's output

403

cat <<'EOF' | muse patch "src/auth.py::generate_token" --body -

404

def generate_token(user_id: str, ttl: int = 3600) -> str:

405

payload = {"sub": user_id, "exp": time.time() + ttl}

406

return jwt.encode(payload, SECRET_KEY)

EOF

```

Now the full agent workflow:

411

412

```bash

413

# Agent identifies which function to change

414

muse blame "src/billing.py::Invoice.compute_total"

415

416

# Agent verifies current symbol state

417

muse symbols --file src/billing.py

418

419

# Agent applies the change surgically

420

muse patch "src/billing.py::Invoice.compute_total" --body /tmp/new_impl.py

421

422

# Agent verifies semantic correctness

423

muse status

424

425

# Agent commits with structured metadata

426

muse commit -m "Optimise compute_total: vectorised sum over items"

427

```

428

429

The structured delta captured in that commit will record exactly:

430

- Which symbol changed (address: `src/billing.py::Invoice.compute_total`)

431

- What kind of change (implementation, signature, both)

432

- The old and new content hashes (for rollback, attribution, clone detection)

433

434

And immediately after, any agent in the world can run:

435

436

```bash

437

muse blame "src/billing.py::Invoice.compute_total"

438

```

439

440

And get a one-line answer: this commit, this agent, this change.

---

## The Full Command Matrix

445

446

| Command | What it does | Impossible in Git because… |

447

|---------|-------------|---------------------------|

448

| `muse symbols` | List all semantic symbols in a snapshot | Git has no AST model |

449

| `muse grep` | Search symbols by name/kind/language | `git grep` searches text lines |

450

| `muse query` | Predicate DSL over the symbol graph | Git has no typed graph |

451

| `muse languages` | Language + symbol-type breakdown | Git has no language awareness |

452

| `muse blame` | Per-symbol attribution (one answer) | `git blame` is per-line |

453

| `muse symbol-log` | Full history of one symbol across renames | Git loses history on rename |

454

| `muse detect-refactor` | Classify renames, moves, signature changes | Git cannot reason about symbols |

455

| `muse hotspots` | Symbol churn leaderboard | Git churn is file/line-level |

456

| `muse stable` | Symbol stability leaderboard | Git has no stability model |

457

| `muse coupling` | Semantic file co-change analysis | Git co-change is line-level noise |

458

| `muse compare` | Semantic diff between any two snapshots | `git diff` is line-level |

459

| `muse patch` | Surgical per-symbol modification | Git patches are line-level |

---

## For AI Agents

Muse is the version control system designed for the AI age.

466

467

When millions of agents are making millions of changes a minute, you need:

468

469

1. **Surgical writes** — `muse patch` modifies one symbol, leaves everything else alone

470

2. **Semantic reads** — `muse query`, `muse grep`, `muse symbols` return typed data, not text

471

3. **Instant attribution** — `muse blame` answers "who touched this?" in one command

472

4. **Stability signals** — `muse hotspots`, `muse stable` tell agents what's safe to build on

473

5. **Coupling maps** — `muse coupling` reveals the hidden dependencies agents need to respect

474

6. **Structured history** — every commit stores a symbol-level delta, machine-readable

475

476

Muse doesn't just store your code. It understands it.

---

*Next: [Demo Script →](demo-script.md)*