Why multi-repo workspaces are a must for Claude Code

When I started using Claude Code, I did the obvious thing: cd into a repo, init Claude, and get to work. New repo? New session. It felt right, until it didn’t.

Suddenly, the project grew, and we were handed new responsibilities and additional repositories. Without consciously realizing it, my mind started creating folders, each named after a service and containing its frontend and backend, launching Claude at the root of each:

~/work/service-A/ - init Claude here

├── frontend/

└── backend/

~/work/service-B/ - init Claude here

├── frontend/

└── backend/

~/work/service-C/ - init Claude here

├── frontend/

└── backend/

But we had only just begun to see the tip of the iceberg in that giant microservices architecture: almost ten repos constantly talking to each other. Suddenly, my tidy little habit didn't feel so smart anymore.

Not only did each service's frontend and backend depend on one another, but a web of cross-microservice codependency started growing as we gained access to more and more repositories. Backends were serving multiple frontends and circular dependencies were creeping in.

I wish I had realized this sooner: I needed a workspace.

Wait! What’s a "workspace"?

Nothing magic. Honestly, you're probably already working in one and just haven't called it that.

A workspace is simply a parent folder that holds a bunch of related repos side by side. If you've ever set up something like this:

~/work/my-project/ - (now init Claude here)

├── product-A/

├── product-B/

└── product-C/

...congratulations, that's a workspace. The parent folder isn't a Git repo itself, it's just a shelf. Each subfolder is its own independent Git repository doing its own thing.

The only real "trick" is where you point Claude. Open it in the parent folder (my-project/) instead of inside one of the child folders, and suddenly it can see, share, and retain memory and context from all of them at once.

I am honestly ashamed it took me so long to discover this. Now, every time I see someone starting Claude inside an isolated sub-repo, I feel like pulling them aside to give them a friendly intervention.

Why does this matter?

You might think, "Well, Claude already works fine per repo, right?" Sure, but I was missing out on a massive amount of leverage. Here is what dramatically improved:

Cross-repo context, for free: Claude sees all your repos simultaneously. It traces data across boundaries and you benefit from shared memory across your projects, as well as a shared CLAUDE.md. Of course I still have my sub-repo CLAUDE.md, but the workspace’s one has all the shared rules.

Write org-wide rules once: With a session per repo, project context gets duplicated and inevitably drifts. At the workspace level, you get a clean hierarchy: a root file for global rules, how repos relate, commit conventions, shared auth setups, and per-repo files for specifics.

True full-stack workflows: With a workspace, you can feed a Figma design to Claude, and with full context over both frontend and backend repos, it can help define and scaffold the API contract in one go to seal the deal, working on both sides at once.

Shared tooling where it belongs: A lot of cross-repo work isn't feature code, it's glue. Think deploy scripts that tag and ship each repo, or custom reusable skills. When Claude runs at the root, all those tools live in one place, available to every repo at once instead of being duplicated and going out of sync.

Zero mental context-switching: My brain gets to focus on solving the actual engineering problem instead of babysitting the tooling.

Uncommitted client context: It’s the perfect spot to keep private documentation, .md files, or client preferences that you don’t want to commit to Git, but still need as a general source of truth for Claude. Start treating that folder not only as a place for code files, but for any document that could provide useful context, such as meeting notes or even invoices.

The anatomy of my workspaces

Today, my workspace structure usually looks something like this:

~/work/my-project/ - (always init Claude here)

├── CLAUDE.md # Global context & architecture rules

├── CLAUDE.local.md # Personal preferences

├── commands/ # Shared CLI commands

├── docs/ # Project notes & client specs

├── hooks/ # Automation hooks

├── deploy.sh # Global scripts

├── skills/ # Reusable Claude skills

├── product-A-frontend/ # Git repo 1

├── product-A-backend/ # Git repo 2

├── product-B-frontend/ # Git repo 3

└── product-B-backend/ # Git repo 4

Note on the one trade-off: The only minor drawback is managing repo-specific skills or commands. However, scoping them clearly inside sub-folders or referencing them explicitly from the root CLAUDE.md keeps things running smoothly.

The honest caveat

This isn't a universal law, and I'd be lying if I said it was. If your project is a single repo, a monolith or a true monorepo where frontend and backend live together then opening Claude right there inside the repo is exactly what you should do. Don't overthink it.

The workspace setup earns its keep precisely when you have several repositories that talk to each other.