virtual-monorepo

virtual-monorepo

A Claude Code plugin for managing virtual (logical) monorepos — one shared branch (typically a JIRA id) across multiple repositories, with all work done in git worktrees grouped per-branch under a single parent directory.

Think of it as the multi-repo counterpart to Claude Code's built-in worktree support: that gives you parallel branches in one repo; this gives you parallel branches across all the repos that need to change together.

This is the reference implementation of Pattern 4: Agent-Assisted Workspace Management from Managing Claude Code Across Multiple Repositories.

What you get

Six skills, namespaced under the virtual-monorepo plugin:

Skill	What it does
virtual-monorepo:init <branch>	Ensure a main clone exists per repo, then add a worktree per repo at <worktree_root>/<branch>/<repo> on a branch named <branch>.
virtual-monorepo:status <branch>	Per-repo summary: branch, dirty file count, ahead/behind upstream, distance from default branch, last commit.
virtual-monorepo:sync <branch>	In submodule mode: pull root repo and refresh submodule pointers. Then per worktree: git fetch origin && git rebase origin/<default>. Stops on first conflict.
virtual-monorepo:test <branch>	Run each repo's configured test command (TEST_CMD_<repo> / TEST_CMD / --cmd=). Repos with no command configured are skipped.
virtual-monorepo:exec <branch> -- <cmd>	Run an arbitrary shell command in every worktree, with per-repo headers and aggregated exit code. The general-purpose primitive that backs virtual-monorepo:test for ad-hoc commands.
virtual-monorepo:teardown <branch>	Verify every worktree is clean (no uncommitted / unpushed work), then git worktree remove each and drop the per-branch dir. --force skips the cleanliness check.

Vocabulary (matches the article)

Term	Meaning in this plugin
Root workspace	The directory holding shared context (rules, skills, docs) plus the main clones and the branch-based workspaces. The article's "root workspace project" lives here.
Main clone	A normal git clone of a repo on its default branch, kept under the root workspace at <root>/.main/<repo>. Worktrees attach to it.
Branch-based workspace	The per-JIRA subdirectory <worktree_root>/<branch>/ that groups one worktree per repo. This is what virtual-monorepo:init creates.
Worktree	A git working directory attached to a main clone, on the JIRA branch — <worktree_root>/<branch>/<repo>.

Layout enforced by the plugin

<root_workspace>/                       # the root workspace
├── .workspace.conf                     # manifest: which repos, where worktrees go
├── .main/                              # main clones (one per repo, on default branch)
│   ├── service-a/
│   └── service-b/
└── worktrees/                          # parent of branch-based workspaces
    └── JIRA-123/                       # <-- a branch-based workspace
        ├── service-a/                  # worktree of .main/service-a on JIRA-123
        └── service-b/                  # worktree of .main/service-b on JIRA-123

Pattern enforced:

<worktree_root>/<branch_name>/<repo>

If you'd rather have branch dirs sit directly at the root workspace (no worktrees/ parent), pass --worktree-root=$root_workspace or set WORKTREE_ROOT="." in .workspace.conf.

Install

Inside Claude Code:

/plugin marketplace add edlovesjava/workspace-skills
/plugin install virtual-monorepo@workspace-skills

After install, the skills are available as /virtual-monorepo:init, /virtual-monorepo:status, etc., and Claude will auto-invoke them when the intent matches their descriptions.

Modes

Both modes from the article are supported and can be selected per invocation by flags.

Manifest mode

A .workspace.conf lists repos directly. See examples/manifest-mode/.workspace.conf.

/virtual-monorepo:init JIRA-123

Submodule mode (Pattern 1's first-class root repo)

The root workspace points at an orchestration repo whose .gitmodules defines the constituent repos. See examples/submodule-mode/.workspace.conf.

/virtual-monorepo:init JIRA-123 --root=https://github.com/example/orchestration.git

Inline (no manifest needed)

/virtual-monorepo:init JIRA-123 \
  --repos=service-a=https://github.com/example/service-a.git#main,service-b=https://github.com/example/service-b.git#main \
  --workspace-dir=/tmp/myworkspace

All skills accept the same flags so you can drive any of them without a manifest.

End-to-end demo flow