muse workspace — multi-repository workspaces

A workspace links multiple independent Muse repositories together under a single manifest, giving you a unified status view, one-shot synchronisation, and a clear model for multi-repo projects.

When to use workspaces vs. worktrees

Use cases

• A film score with a melody repo, a harmony repo, and a samples repo
• A machine learning pipeline with a model repo, a dataset repo, and an eval repo
• A micro-service backend where each service lives in its own Muse repo
• An agent swarm where each autonomous agent manages its own state repo, and the coordinator workspace tracks them all

Workspace manifest

The manifest lives at .muse/workspace.toml:

[[members]]
name   = "core"
url    = "https://musehub.ai/acme/core"
path   = "repos/core"
branch = "main"

[[members]]
name   = "sounds"
url    = "https://musehub.ai/acme/sounds"
path   = "repos/sounds"
branch = "v2"

Subcommands

muse workspace add <name> <url>

Register a member repository.

muse workspace add core   https://musehub.ai/acme/core
muse workspace add sounds https://musehub.ai/acme/sounds --branch v2
muse workspace add data   /path/to/local/dataset         --path vendor/data

Registration writes the manifest entry. Run muse workspace sync to clone.

muse workspace list

List all registered members with their status.

name                 branch           present  HEAD          url
──────────────────────────────────────────────────────────────────────────────
core                 main             yes      a1b2c3d4ef56  https://musehub.ai/acme/core
sounds               v2               yes      deadbeef0012  https://musehub.ai/acme/sounds
data                 main             no       (not cloned)  /path/to/local/dataset

muse workspace remove <name>

Remove a member from the manifest. The member's directory is not deleted.

muse workspace remove sounds

muse workspace status

Rich status view for all members.

Workspace: /Users/me/myproject

✅  core                 branch=main  head=a1b2c3d4ef56
     path: /Users/me/myproject/repos/core
     url:  https://musehub.ai/acme/core

❌  data                 branch=main  head=not cloned
     path: /Users/me/myproject/repos/data
     url:  /path/to/local/dataset

muse workspace sync [name]

Clone or pull all members (or one named member).

muse workspace sync         # sync everything
muse workspace sync core    # sync only 'core'

• If a member directory does not exist, muse clone is run to fetch it.
• If a member directory already exists, muse pull is run to update it.

Agent workflows

Coordinator + worker pattern

# Coordinator workspace tracks N worker repos:
muse workspace add worker-001 https://musehub.ai/swarm/worker-001
muse workspace add worker-002 https://musehub.ai/swarm/worker-002
muse workspace add worker-003 https://musehub.ai/swarm/worker-003

# Sync all workers to latest:
muse workspace sync

# Status across all:
muse workspace status

Release pipeline

# Pin all members to release branches before archiving:
muse workspace add core    https://musehub.ai/acme/core    --branch release/v2
muse workspace add sounds  https://musehub.ai/acme/sounds  --branch release/v2
muse workspace sync

# Archive each member:
for member in repos/*/; do
    (cd "$member" && muse archive --output "../../archives/$(basename $member).tar.gz")
done

Exit codes