Run multiple BMad Method workspaces (BMad is an agent-driven planning and development workflow) out of one repo. One shared _bmad/ core, one workspace active at a time, switched with a symlink swap.

BMad assumes one project per repo. If several workspaces share the same agents and workflows, you'd otherwise duplicate _bmad/ everywhere. This keeps a single core and isolates each workspace's artifacts.

Meta Router is an independent tool that builds on the BMad Method; it is not affiliated with or endorsed by the BMad project.

Browse a live example →: a generated metarepo with two workspaces, sample artifacts, and the worktree setup. Regenerated on every push to main.

Quick start

Requirements: Node.js ≥ 20 (for BMad), git, bash. On Windows, set core.symlinks=true (WSL works out of the box).

One-liner: fetch a tagged release and run setup, no clone needed. Pin a version with META_ROUTER_REF, or omit it to track the latest release:

# pinned to a tag (reproducible)
curl -fsSL https://raw.githubusercontent.com/Code-and-Sorts/meta-router/v0.1.0/install.sh \
  | META_ROUTER_REF=v0.1.0 bash -s -- my-metarepo

# or track the latest release
curl -fsSL https://raw.githubusercontent.com/Code-and-Sorts/meta-router/main/install.sh \
  | bash -s -- my-metarepo

Anything after -- is passed to setup, and the BMAD_SETUP_* environment variables are honored, so this works non-interactively in CI too.

Via the skill: install it, then ask your agent to set up a metarepo; the skill runs setup from wherever it's installed.

gh skill install Code-and-Sorts/meta-router meta-router

Or clone and run setup yourself:

git clone https://github.com/Code-and-Sorts/meta-router
bash meta-router/skills/meta-router/scripts/setup.sh my-metarepo

Setup asks six things: output folder name (default features), docs folder name (default docs), your BMad skill level, which agent tool you use (Claude Code, GitHub Copilot, or Codex), which workspaces to create, and whether to enable GitHub sync. Then it installs BMad and scaffolds everything. It also runs non-interactively for CI; see the setup environment variables.

After that, drive the metarepo either way.

Use the skill: generated metarepos include the meta-router agent skill automatically (scripts and templates ship inside it at .claude/skills/meta-router/), so your agent can switch workspaces, cut worktrees, and run the GitHub sync on request. Or call the bundled script directly:

cd my-metarepo
router=.claude/skills/meta-router/scripts/meta-router.sh   # .github or .codex for other tools
bash $router init food-inventory   # create + switch to a workspace
bash $router switch camera-app     # change active workspace
bash $router list                  # list workspaces

switch repoints a handful of symlinks at the repo root (features/, docs/, skills, repos/, implementation/) so BMad reads and writes the active workspace's artifacts; nothing is copied or deleted.

Documentation

• How it works: the symlink swap, shared vs. per-workspace context, and the metarepo layout.
• Reference: every meta-router.sh command, configuration, setup env vars, and the file manifest.
• Source repos and worktrees: declare each workspace's repos in repos.yaml, then cut per-story git worktrees across them.
• GitHub Issues + Projects sync: optionally mirror BMad artifacts to issue trees and a project board.

Contributing

Issues and PRs welcome; CONTRIBUTING.md covers tests, shellcheck, and PR expectations.