virtual-monorepo

Stop re-explaining your multi-repo system to Claude Code every session.

Claude Code works one repo at a time. Real systems don't live in one repo — a frontend, a backend, and a shared library are three repos, and the interesting work lives between them. virtual-monorepo is a Claude Code skill that wires your separate repos into one symlink-based workspace and writes a workspace-level CLAUDE.md that describes how the whole system fits together, so you hand Claude the map once instead of narrating it every time.

What it does

Point Claude at one of your repos and ask it to set up the workspace. The skill:

• Discovers sibling repos (dirs with a .git), skipping node_modules and build output, and proposes the set before touching anything.
• Creates a workspace directory and symlinks each real repo into it.
• Generates a workspace-level CLAUDE.md by reading each repo once: a one-sentence system overview, a one-paragraph summary per repo, a dated cross-repo relationship snapshot (who calls whom, shared packages — derived from manifests and API-client code), and how-to-run pointers.

One-shot. No index, no daemon, no database. Just plain symlinks plus one markdown file you can open and read. When the system drifts, you ask Claude to regenerate the map by re-reading the repos — there is nothing running in the background to keep fed.

Install

npx skills add PrecisionUtilityGuild/virtual-monorepo --skill virtual-monorepo

Or install manually: copy skills/virtual-monorepo/ into ~/.claude/skills/ (global) or your project's .claude/skills/.

Usage

1. Sit in one of your repos and start Claude Code there.
2. Ask Claude to set up a virtual monorepo workspace. It proposes the sibling repos it found, symlinks the ones you confirm, and writes the workspace CLAUDE.md.
3. Launch future sessions from the workspace directory (cd <workspace> && claude): the generated CLAUDE.md loads as context and every repo is reachable through its symlink.

Built-in alternative — --add-dir. Claude Code already lets you add an extra root to a running session with claude --add-dir <other-repo>. That is enough for the ad-hoc, single-session case ("also look at that repo, once"). The workspace earns its keep when you do cross-repo work recurringly and want a persistent, trustworthy system map rather than re-adding roots and re-explaining relationships each time.

Receipts

Tested live on a real two-repo system on 2026-07-15, audited line-by-line against the code:

• Map accuracy: 23/24 factual claims true (~96%), zero fabrications. The one imperfect claim was a simplification (named four source layers where the repo has six plus loose files), not an error.
• It caught a real repo lie. One repo's README claimed its content came from an npm dependency, but that dependency was absent from package.json; the actual mechanism was a sync script plus committed content. The generated map flagged the discrepancy instead of parroting the README.

Honest limit, stated plainly: in an A/B test on a single cross-repo question, the workspace did not beat plain --add-dir on answer quality (the --add-dir control was rubric-complete; the workspace arm missed one detail). It was somewhat faster and cheaper on that run, but at n=1 that isn't significant. The value here is ergonomics and a trustworthy persistent map, not better single-question answers — and we won't claim otherwise.

Known limitations

• Headless sessions can't finish setup. In non-interactive sessions (claude -p) the permission system denies ln -s, so unattended symlink creation can't complete. The skill hands back the exact commands to run instead of trying to route around the gate. Interactive sessions are unaffected.
• Windows needs Developer Mode enabled for symlinks (ln -s maps to mklink /D).
• The map is a snapshot, not a live index. You regenerate it on demand; it goes stale if the system changes and you don't.

What it does not do

The absence of machinery is the point, so the skill refuses — permanently, under any framing — to build:

• a background process, watcher, or daemon;
• a database or SQLite file;
• a JSON/YAML index or per-file catalog of your repos.

A repo summary is one paragraph of prose, not a file listing. If you ask it to "keep the workspace in sync automatically" or "index the code," it declines and regenerates on demand instead. Everything it makes is a directory of symlinks and one markdown file you can read, edit, and delete by hand.

License

MIT — see LICENSE.