# 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.

---

## 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.

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

Verify:

```bash
muse --version
muse auth whoami
```

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

```bash
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:

```json
{"hub": "https://staging.musehub.ai", "key_path": "~/.muse/keys/musehub_ai.pem",
 "algorithm": "ed25519", "fingerprint": "<sha256hex>"}
```

There are no passwords, no tokens, no JWTs. Every request is signed with your Ed25519
private key. 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.

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

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

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

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

```bash
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

```bash
# 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:

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

### Migrate into a separate directory

```bash
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:

```bash
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:

```bash
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:

```bash
# Add the remote (create the repo on MuseHub first if it doesn't exist)
muse remote add local http://localhost:10003/<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:

```bash
muse hub connect http://localhost:10003
```

---

## Step 4 — Learn the Full Muse Workflow

Read [AGENTS.md](../../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:

| Old reflex | Muse replacement |
|-----------|----------------|
| `rg "FunctionName"` | `muse code grep "FunctionName"` |
| Read whole file to find one function | `muse code cat "file.py::FunctionName"` |
| `git log` / `git blame` | `muse log` / `muse code symbol-log "file.py::Symbol"` |

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