---
name: multi-repo-workspace-setup
description: Set up or repair an "umbrella" workspace so one Claude Code session can work across several git repositories. Use when the user wants to work on multiple repos in one session, asks about multi-repo or cross-repo workflows with Claude Code, or has a parent folder of sibling repos that needs shared instructions, a commit guard hook, or safe git rules.
---

# Multi-repo umbrella workspace

Source guide: https://roni.io/guides/claude-code-multi-repo-workspace-setup/ by Roni Gorodetsky.

## Goal

A parent folder that holds the user's repositories side by side. Sessions start from the
parent. The assistant can change several repos in one conversation, knows how they connect,
and cannot commit or push without approval.

## Build it in this order

1. **Parent folder.** Repos sit side by side inside it. Never run `git init` in the parent.
   Each repo keeps its own history and remote.
2. **Workspace CLAUDE.md** in the parent, short, with four sections: a table of repos (folder,
   tech, role), how the pieces communicate (protocols and where routes or handlers live),
   cross-repo change patterns (for each kind of change, every place it touches), and what not
   to do. To fill it in, inspect each repo: read its README, package or build file, and route
   definitions. Ask the user to confirm the change patterns, since those encode their product.
3. **Per-repo CLAUDE.md** in each repo for its own conventions. It loads the first time a file
   in that repo is read with the Read tool. State in the workspace file that it must not be
   re-read once loaded.
4. **.ignore** in the parent listing dependency and build folders for the stacks present.
5. **Commit guard.** `.claude/settings.json` with a PreToolUse hook, matcher `Bash`, running
   `.claude/hooks/commit-guard.sh` (executable). The script reads the tool call JSON on stdin,
   exits 0 if the command contains `ship-ok`, exits 2 with a message on stderr if it matches
   `git commit`, `git push`, `npm version`, `npm publish` or `yarn version`, and exits 0
   otherwise.
6. **Rules in the workspace file:** no commit, push or version bump without the user saying
   ship; every git command as `git -C <repo> ...`; print and check the remote before a push;
   one commit per repo.
7. **Memory rule:** store lessons, decisions and preferences. Never status notes.
8. **Parallel sessions (only if the user runs several):** `git status` before staging and
   never stage a file you did not edit; stage by name, never `git add -A`; never `git stash`,
   use a `git worktree`.

## Verify

Ask for one small change that touches two repos. Confirm both are edited in one
conversation, that the assistant stops before committing, and that after "ship" each repo
gets its own commit and push. If it commits without being told, the hook is not wired: check
the settings file location and that the script is executable.

## Why each rule exists

- Explicit `git -C`: the shell directory can reset between commands, and a push from the wrong
  directory can send one repo's history to another repo's remote.
- Stage by name: in a shared checkout, staging everything ships another session's
  half-finished work and can break the build.
- Hook, not just a written rule: a written rule is followed most of the time, and that is not
  enough for anything that deploys.
- Do not cap context or downgrade helper models to save cost. It made the work worse.
  Clear the session between unrelated tasks instead.