MuseHub

The collaboration hub for the agent era.

MuseHub is what GitHub would look like if it were designed from scratch for AI agents, multidimensional state, and version control that goes beyond text files.

Powered by Muse VCS — the world's first domain-agnostic, multi-dimensional version control system. Where Git tracks text, Muse tracks structured state across any domain: Code, MIDI, Genomics, Circuit Design, 3D scenes — and any domain you define.

MuseHub is the remote layer: push commits, open merge proposals, track issues, browse repos, publish releases, and give AI agents complete programmatic access via a best-in-class MCP integration built in pure Python, no external SDK.

Why MuseHub

Git was designed in 2005 for one thing: tracking text diffs. It has no concept of multidimensional state, no first-class agent authorship, no symbol-level intelligence, and no provenance trail. Every tool built on top of Git inherits those limits.

Muse starts over. MuseHub extends that foundation with the collaboration infrastructure the agent era actually demands:

Quickstart

# 1. Start the stack (Postgres + app)
docker compose up -d

# 2. Run migrations
docker compose exec musehub alembic upgrade head

# 3. Seed development data
docker compose exec musehub python3 scripts/seed_musehub.py

Requirements: Python 3.14+ · PostgreSQL 16+ · Node.js 22+

Web UI: https://localhost:1337 Interactive API docs: https://localhost:1337/docs (requires DEBUG=true) OpenAPI spec: https://localhost:1337/api/openapi.json

Connecting a Muse Repo

# Add MuseHub as a remote
muse remote add local https://localhost:1337/repos/gabriel/<repo>

# Push
muse push local dev

# Pull
muse pull local dev

Create a repo on MuseHub before the first push:

TOKEN=$(python3 -c "
import tomllib, pathlib
data = tomllib.loads(pathlib.Path.home().joinpath('.muse/identity.toml').read_text())
print(data['localhost:1337']['token'])
")

curl -s -X POST https://localhost:1337/api/repos \
  -H "Content-Type: application/json" \
  -H "Authorization: MSign handle=\"gabriel\" ts=<ts> sig=\"<sig>\"" \
  -d '{"owner":"gabriel","name":"my-repo","description":"..."}'

Agent Provenance

Every commit pushed to MuseHub can carry structured agent metadata. The web UI and API surface it everywhere — file tree, commit stream, merge proposals, releases.

muse commit -m "feat: redesign auth layer" \
  --agent-id    "agentception-worker-42" \
  --model-id    "claude-sonnet-4-6" \
  --toolchain-id "agentception/v1" \
  --sign

Fields stored on every commit:

Symbol Intelligence (Intel)

The Intel layer computes a live health score for every repo from its symbol graph. Available in the web UI under the Intel tab and via MCP.

health_score      0–100 composite score
health_label      Excellent / Good / Fair / Poor / Critical
hotspots          Symbols changing too frequently (churn risk)
dead_candidates   Symbols untouched ≥ 90 days with non-zero blast radius
blast_risk        Symbols whose change triggers widespread co-changes
coupling_pairs    Pairs that always change together (hidden dependency signal)
velocity          Commit velocity by week
breaking_changes  Breaking commits in the last 30 days

URL Scheme

/{owner}/{slug}                    Repo home — code, file tree, README
/{owner}/{slug}/commits            Commit history + DAG graph
/{owner}/{slug}/commits/{id}       Commit detail + provenance + diff
/{owner}/{slug}/proposals          Merge proposals
/{owner}/{slug}/issues             Issue tracker
/{owner}/{slug}/intel              Symbol intelligence dashboard
/{owner}/{slug}/insights           Velocity + agent attribution charts
/{owner}/{slug}/releases           Published releases
/{owner}/{slug}/graph              Commit DAG visualizer

musehub://{owner}/{slug}           MCP resource URI
mcp://musehub/{owner}/{slug}       MCP clone URI

MCP Integration

MuseHub implements the full MCP 2025-11-25 specification in pure Python async — no external MCP SDK. Agents get complete capability parity with the web UI.

Transports

Session lifecycle: POST initialize → receive Mcp-Session-Id → include on all subsequent requests → DELETE /mcp to close.

Cursor / VS Code Setup

{
  "mcpServers": {
    "musehub": {
      "command": "python",
      "args": ["-m", "musehub.mcp.stdio_server"],
      "cwd": "/path/to/musehub"
    }
  }
}

Agent Onboarding Sequence

musehub_whoami()                                    # 1. confirm auth
musehub_list_domains(verified=True)                 # 2. discover state models
musehub_get_context(owner="gabriel", slug="repo")   # 3. read before writing
musehub_create_issue(...)                           # 4. open work item
muse_push(repo_id=..., branch=..., commits=[...])  # 5. push state
musehub_create_proposal(...)                        # 6. open merge proposal
musehub_merge_proposal(...)                         # 7. merge

All repo-scoped tools accept either repo_id (UUID) or owner + slug. The dispatcher resolves either form transparently.

Tools — 40 total

Read tools (20+)

Write tools (15+)

Resources — 29 total

Cacheable, URI-addressable reads via the musehub:// scheme.

musehub://trending
musehub://me
musehub://me/notifications
musehub://me/starred
musehub://me/feed
musehub://repos/{owner}/{slug}
musehub://repos/{owner}/{slug}/branches
musehub://repos/{owner}/{slug}/commits
musehub://repos/{owner}/{slug}/commits/{id}
musehub://repos/{owner}/{slug}/tree/{ref}
musehub://repos/{owner}/{slug}/blob/{ref}/{path}
musehub://repos/{owner}/{slug}/issues
musehub://repos/{owner}/{slug}/issues/{number}
musehub://repos/{owner}/{slug}/proposals
musehub://repos/{owner}/{slug}/proposals/{number}
musehub://repos/{owner}/{slug}/releases
musehub://repos/{owner}/{slug}/releases/{tag}
musehub://users/{username}

Prompts — 10 total

Workflow guides that teach agents how to chain tools correctly:

Full reference: docs/reference/mcp.md

Auth

Authorization: MSign handle="gabriel" ts=<ts> sig="<sig>"

Public repo reads and all MCP read tools are unauthenticated. Write endpoints require an MSign request signature.

Register your Ed25519 public key via muse hub connect or the MuseHub identity API. The muse CLI signs requests automatically using the key registered in ~/.muse/identity.toml.

Tokens live in ~/.muse/identity.toml:

["localhost:1337"]
type  = "human"
name  = "gabriel"

Architecture

musehub/
  api/routes/musehub/   Route handlers (thin HTTP layer)
  api/routes/mcp.py     POST /mcp — HTTP Streamable MCP endpoint
  services/             Business logic modules
  db/                   SQLAlchemy ORM models (Postgres)
  models/               Pydantic request/response models
  mcp/
    dispatcher.py       Async JSON-RPC 2.0 engine (no external SDK)
    tools/              40-tool catalogue
    resources.py        29 musehub:// resources
    prompts.py          10 workflow prompts
    stdio_server.py     stdio transport for local dev
  templates/musehub/    Jinja2 + HTMX + Alpine.js web UI
  auth/                 MSign auth middleware (Ed25519)
  config.py             Pydantic Settings (env vars)

tools/
  typing_audit.py       Static typing violation scanner (ratcheted at 0 violations)

Developer Tools

# Type audit — ratcheted at 0 violations
python tools/typing_audit.py --dirs musehub/ tests/ --max-any 0

# JSON output
python tools/typing_audit.py --dirs musehub/ tests/ --json artifacts/typing_audit.json

License

MIT — see LICENSE.

bump prebuild mpack