Using Claude Code with Multiple Repositories
Claude Code is very good at working inside the folder you start it in. Most real systems don't live in one folder, though. A frontend calls an API in another repository, that API depends on a shared library in a third, and the infrastructure is defined in a fourth. This article explains what goes wrong when Claude Code can only see one of those, and compares the ways to fix it.
Why one repository isn't enough
When you ask Claude Code to change something, it reads the files it can reach and reasons from them. If the code that matters lives somewhere else, Claude has to guess. That's where cross-repository mistakes come from:
- It changes an API response without knowing which clients consume it.
- It re-implements a helper that already exists in a shared package.
- It "fixes" a bug in the caller when the real cause is in the service being called.
- It can't tell you what else will be affected by a change.
None of these are model failures. Claude simply wasn't given the rest of the system.
Option 1: Start Claude Code in a parent folder
If all your repositories are cloned side by side, you can start Claude Code in the folder that contains them. Claude can now read across all of them.
- Good for
- small setups with a few repositories.
- Limits
- Claude still has to search file by file to discover how the repositories connect, which gets slow and token-heavy as the system grows.
Option 2: Add extra directories
Claude Code can work with additional directories beyond the one it started in, using the --add-dir flag or the /add-dir command during a session.
claude --add-dir ../shared-lib --add-dir ../api- Good for
- a task that clearly touches two or three known repositories.
- Limits
- you have to know in advance which repositories matter. The hard question is usually "what else does this touch?", and this option doesn't answer it.
Option 3: Describe the system in CLAUDE.md
Claude Code reads CLAUDE.md files for project instructions. You can write down which repositories exist, what each one does, and how they talk to each other.
- Good for
- giving Claude a map of the system.
- Limits
- it's handwritten and goes stale. It tells Claude that a dependency exists, not where in the code it is.
Option 4: Use a cross-repository code graph
The most complete approach is to map how your repositories connect once, ahead of time, and give the agent that map, so it doesn't rediscover the links file by file. CodeZero does this. It's a VS Code extension that works alongside the Claude Code you already have installed, using your existing Claude subscription or credentials. It doesn't replace Claude Code; it supplies the context layer:
- One graph across repositories. Add the repositories you work on from inside CodeZero; they're indexed on your machine and linked into one graph.
- Relationships are already mapped. The Code Graph shows how modules, files, data and repositories connect, including dependencies that cross repository boundaries.
- Your local work stays in reach. The agent reads your working tree directly, including uncommitted changes; the graph covers each repository's main branch.
- Edits stay under your control. Planned mode blocks edits until you approve the plan, and Normal mode asks you to confirm each edit.
Which option should you use?
| Situation | Best fit |
|---|---|
| 2–3 repositories, all cloned, change is obvious | Parent folder or --add-dir |
| Team wants Claude to "know" the architecture | CLAUDE.md, plus one of the above |
| Many repositories, changes ripple across services | A cross-repository code graph such as CodeZero |
FAQ
Which repositories can CodeZero see?
The ones you add from inside CodeZero. Clone a repository, add it with the + button, and CodeZero indexes it on your machine and links it with your other repositories.
Does CodeZero replace Claude Code?
No. Claude Code still runs the work with your own credentials. CodeZero provides the cross-repository context.