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. Repositories you haven't cloned are still invisible.
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 an organisation-wide index
The most complete approach is to index all of your organisation's repositories once and give the agent access to that index. 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:
- Repositories you haven't cloned are still readable. CodeZero uses your organisation's repository index, so Claude can read context from repositories that aren't checked out on your machine.
- Relationships are already mapped. The Code Graph shows how modules, files, data and repositories connect, including dependencies that cross repository boundaries.
- Local work takes priority. When a repository is checked out, CodeZero prefers your working tree, because it includes your current branch and uncommitted changes.
- Edits stay safe. Indexed repositories are read-only. If an approved plan needs to change one you haven't cloned, CodeZero offers to clone it, and you choose where.
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, not all cloned, changes ripple across services | An organisation-wide index such as CodeZero |
FAQ
Can Claude Code read a repository I haven't cloned?
Not on its own. With CodeZero, it can use read-only context from any repository your organisation has indexed.
Does CodeZero replace Claude Code?
No. Claude Code still runs the work with your own credentials. CodeZero provides the cross-repository context.