Getting Started with Muse

Everything a new contributor needs to switch from Git to Muse — install, uninstall, migrate an existing repo, and understand the full agent-era workflow.

Dev Setup (contributors only)

If you are hacking on Muse itself (not just using it), run the dev setup script instead of the user installer below. It builds a clean virtualenv from pyproject.toml, installs muse in editable mode (pip install -e .) with all grammars and dev tools, and wires ~/bin/muse to the venv. Re-run it any time dependencies drift:

bash ~/ecosystem/muse/dev-setup.sh

The dev venv lives at ~/ecosystem/muse/.venv and is separate from the user install path (~/.local/share/muse/venv). You can run both side-by-side to dog-food the installer experience without touching your dev environment.

Step 1 — Install

Run the installer from MuseHub. It requires Python 3.14+ and installs muse into a dedicated virtualenv at ~/.local/share/muse/venv, then symlinks the muse binary to ~/.local/bin. No PyPI — the package is downloaded directly from the MuseHub instance. Muse is currently implemented in Python and will be ported to Rust.

curl -fsSL https://staging.musehub.ai/install.sh | sh

Verify:

muse --version
muse auth whoami

If you have not yet registered an identity with a hub, do that now:

muse auth keygen --hub https://staging.musehub.ai
muse auth register --hub https://staging.musehub.ai --handle <your-handle>
muse auth whoami

muse auth keygen --json outputs the key fingerprint — keep a copy somewhere safe:

{"hub": "https://staging.musehub.ai", "algorithm": "ed25519",
 "fingerprint": "sha256:<64-hex>", "hd_path": "m/1075233755'/0'/0'/0'/0'/0'"}

There are no passwords, no tokens, no JWTs. Every request is signed with an Ed25519 key derived in memory from the BIP39 mnemonic stored in the OS keychain — no key file is ever written to disk. The server holds only the public key.

Step 2 — Uninstall (when needed)

The uninstall script removes the venv and the ~/.local/bin/muse symlink. It deliberately leaves ~/.muse intact — your keys, history, and identity store are never deleted automatically.

curl -fsSL https://staging.musehub.ai/uninstall.sh | sh

To fully clean up (keys and all), remove ~/.muse manually after running the script:

rm -rf ~/.muse   # only if you are decommissioning this machine entirely

To rotate a key or deregister a specific hub without removing the binary:

muse auth logout --hub https://staging.musehub.ai   # removes local key entry from ~/.muse/identity.toml

muse auth logout removes only the local key entry — there is no server-side session to invalidate (MSign is stateless). Useful for key rotation or decommissioning a machine.

Step 3 — Migrate an Existing Git Repository

muse code migrate replays a Git commit graph into a Muse repository. It preserves author names, emails, and committer timestamps verbatim.

Quick start

# Migrate the current directory (replays main by default)
cd /path/to/your-git-repo
muse code migrate

# Migrate all local branches
muse code migrate --all

# Migrate specific branches
muse code migrate --branch main dev feat/x

# Preview without writing anything
muse code migrate --all --dry-run

# Stream structured progress (essential for agent pipelines and large repos)
muse code migrate --all --json

Incremental migration

If you have already migrated and want to pick up new commits:

# Only replay commits after a known git SHA
muse code migrate --from-ref abc123def456

Migrate into a separate directory

muse code migrate /path/to/git-repo --target /path/to/new-muse-repo

Add custom exclusion patterns

The default exclusions cover build artifacts and editor swap files. Add your own:

muse code migrate --exclude "dist/" "*.lock" "vendor/"

JSON progress events (agents and CI)

With --json, the command streams NDJSON to stdout throughout the run — no silent multi-minute waits. Every line is a valid JSON object:

{"event": "branch_start", "branch": "main", "total": 1247}
{"event": "progress", "branch": "main", "committed": 100, "total": 1247}
{"event": "progress", "branch": "main", "committed": 200, "total": 1247}
...
{"event": "branch_done", "branch": "main", "committed": 1247}
{"event": "done", "branches": ["main", "dev"], "dry_run": false, ...}

Parse the final done event for a structured summary:

muse code migrate --all --json | grep '"event":"done"' | jq '.'

Connect to MuseHub and push

After migration, connect your new Muse repo to a remote and push:

# Add the remote (create the repo on MuseHub first if it doesn't exist)
muse remote add local https://localhost:1337/<handle>/<repo>

# Push
muse push local main
muse push local dev

If the push returns 404 ("Repository not found on remote"), the repo does not yet exist on MuseHub. Create it via the API then retry:

muse hub connect https://localhost:1337

Step 4 — Learn the Full Muse Workflow

Read AGENTS.md next. It covers:

• The three-repo ecosystem layout (muse, musehub, agentception)
• Every muse command with examples — commit, branch, merge, push, tag, release
• Muse Code Intelligence: muse code grep, muse code cat, muse code impact, muse code deps
• Multi-agent coordination with muse coord
• Worktrees for parallel branch work
• Muse Flow — branch topology designed for agent swarms
• MSign authentication internals
• Provenance metadata on commits (--agent-id, --model-id, --sign)
• Non-negotiable quality rules (no legacy, no deprecated, no dead code)

The three most important habit changes from Git:

Never run git or gh in this ecosystem. Muse and MuseHub are the only VCS tools.