Install

Requirements

Per track. Nothing below Track 1 needs anything Track 1 does not.

The code CLI: in VS Code, Command Palette → Shell Command: Install 'code' command in PATH.

Track 1

The engine, alone

Two binaries, mezz and elevator, and nothing else. This is all you need for CLI analysis, CI checks, and giving a coding agent the graph over MCP — no UI, no editor.

Without cloning

cargo install --git https://github.com/llvator/mezzanine.git --force

From a checkout, if you also want the scripts and demos

git clone https://github.com/llvator/mezzanine.git
cd mezzanine
cargo install --path . --force      # mezz and elevator into ~/.cargo/bin

Check it works

mezz analyze . -f json -o analysis.json
mezz analyze . -f ascii              # or just look at it

If mezz: command not found, ~/.cargo/bin is not on your $PATH.

Set a repository up

Optional, and worth the ten seconds. mezz init writes the file a repo would otherwise hand-write: it walks the tree — honouring .gitignore, so vendored code never votes — and pins the languages the repo is actually written in, plus spec_dir when every .elv sits in one directory.

mezz init                 # pins this repo's languages in .mezz/settings.json
mezz init --vscode        # also adds the start / open / stop UI tasks

• Never a defaulted key. Spelling out today's defaults would freeze them into every repo that ran it, so the file carries only what the tree proves.
• Markdown is excluded on purpose. A pinned language list is exactly where opt-in docs would quietly stop being opt-in.
• --vscode adds three tasks — start, open, stop the browser UI — merged into an existing tasks.json by label. A tasks.json it cannot parse is left untouched with the tasks printed to paste, because VS Code allows comments there and rewriting the file would delete them.

What the engine can do →

Track 2

Add the browser visualizer

The UI is served by the binary you just installed — there is no separate thing to install, only a server to start. mezz watch analyses one folder and keeps it current as you save:

mezz watch . --port 3200        # one repo, live, re-analysed on save
# open http://127.0.0.1:3200

mezz serve is the other shape: several already-analyzed repositories behind one API, with a picker in the UI. It is what the hosted /visualizer was baked from.

# several analyzed repos under one API, each seeded from a local path
mezz serve --port 3400 \
  --seed my-org__api=/code/api \
  --seed my-org__web=/code/web

Where the UI comes from

install.sh builds the UI and copies it to a ui/dist beside the installed binary, which is the location mezz watch looks in when it is not launched from a checkout. It resolves that directory from CARGO_INSTALL_ROOT / CARGO_HOME rather than assuming ~/.cargo, so a moved cargo home still gets one.

• No node toolchain, or you only want the binaries: MEZZ_SKIP_UI=1 ./scripts/install.sh. The engine, MCP and CLI are unaffected — mezz watch starts and explains how to point it at a UI.
• Installing from a checkout without the script: ./scripts/build.sh --ui writes <repo>/ui/dist, which mezz watch finds when run from the repo root.

The startup banner names the directory it resolved, and the build stamp in the corner of the page names the commit of the bundle being served — between them, a stale copy shadowing a rebuild is visible rather than mysterious.

Live versus frozen, and why it can be hosted →

Track 3

Add the VS Code extension

One script, because the extension needs both pieces below it — the binary it spawns and the UI it embeds:

git clone https://github.com/llvator/mezzanine.git
cd mezzanine
./scripts/install.sh           # binaries + extension, one step

That installs both binaries into your cargo bin directory, builds the browser UI beside them, then packages the VS Code extension and installs it into your default profile. Reload VS Code and the Mezzanine icon appears in the activity bar.

• Target specific VS Code profiles: ./scripts/install.sh Work Personal
• Different editor CLI: MEZZ_CODE_CLI=cursor ./scripts/install.sh
• Binaries only — back to Track 1: MEZZ_SKIP_EXTENSION=1 ./scripts/install.sh
• Skip the browser UI too: MEZZ_SKIP_UI=1 ./scripts/install.sh

First run

1. Open a folder.
2. Click the Mezzanine icon in the activity bar.
3. Command Palette → Mezzanine: Open Code Visualizer.
4. In Visual Scopes, tick the folders you want drawn.

Saves trigger a re-analysis, so the graph tracks the code as you work.

The views, the settings, what the editor adds →

Agents (MCP)

Track 1 is enough. mezz mcp speaks MCP over stdio — register it with your client. For Claude Code, a .mcp.json at the project root:

{
  "mcpServers": {
    "mezz": { "command": "mezz", "args": ["mcp"] }
  }
}

Thirteen read-only tools appear. The agent loop shows the order that works.

mezz CLI reference

# One-shot analysis to JSON
mezz analyze ./my-project -f json -o analysis.json

# Filter by language, cap traversal depth
mezz analyze ./my-project -l rust -l python -d 5

# Watch mode — re-analyses on save, serves data + SSE
mezz watch ./my-project --port 3200

# MCP server over stdio, for coding agents
mezz mcp

elevator CLI

Installed alongside mezz by every track — it is the second binary out of the same crate.

elevator ./spec                         # full project map
elevator ./spec --focus f.protocol      # one branch, as an LLM bundle
elevator ./spec --check                 # broken refs, orphans (CI-friendly)
elevator ./spec --code-map              # path → entities; double claims
elevator ./spec --drift --code-root .   # anchors that no longer hold
elevator --docs                         # full language reference

The language guide covers the six entity kinds and the sketch-first method. elevator --docs prints the full reference offline.

Updating

git pull
./scripts/install.sh

Then Cmd+Shift+P → Developer: Reload Window. The script is safe to re-run for any change — it reinstalls both binaries and repackages the extension regardless of what you touched. On Track 1, cargo install --path . --force is the whole update.

Troubleshooting

mezz: command not found / elevator: command not found

cargo install did not run, or ~/.cargo/bin is not on your $PATH.

The visualizer loads but the page is blank

No ui/dist was found. Re-run ./scripts/install.sh without MEZZ_SKIP_UI — it puts one beside the binary. The startup banner names the directory it settled on.

The UI is stale after a rebuild

A copy from an earlier install is shadowing it. The build stamp in the corner names the commit actually being served; re-run ./scripts/install.sh to replace it.

code: command not found

Install the VS Code CLI: Command Palette → Shell Command: Install 'code' command in PATH.

The extension installed but no icon appears

Reload the window — Cmd+Shift+P → Developer: Reload Window.

The extension cannot find the binary

Set mezz.binaryPath to its absolute location.

The graph shows files instead of entities

The auto-level picker escalated because there are too many entities for the viewport. Pin the level to “entity” in View Options, or narrow the Visual Scopes.