Claude Code reads the files it can reach from the folder you start it in. It does not build an index of your code, so it knows nothing about a second repository until you give it a way in. There are three ways: start it in a folder that contains all the repos, add the other repos to the session with --add-dir, or connect a search or documentation service over MCP. Each one settles two separate questions, which files Claude can open and which instructions it loads, and the answers are not always the same.

This guide covers each option with the commands, the settings and the limits, checked against the Claude Code documentation on 2 October 2026.

What Claude Code sees by default

Anthropic describes the approach in its article on large codebases: Claude Code "traverses the file system, reads files, uses grep to find exactly what it needs", runs on the developer's machine, and does not need a codebase index. The same article names the trade-off. It works best when Claude has enough starting context to know where to look.

Two rules decide what a session starts with:

So if you run claude inside orders-api/, the session can read orders-api/ and has its instructions. The billing/ repo next door is outside that: Claude cannot read or edit it without an extra permission grant, and nothing tells Claude it exists.

Option 1: start in a parent folder

Put the repos side by side and start Claude one level up.

work/
  CLAUDE.md          # the map: what each repo is, how they connect
  orders-api/
    CLAUDE.md
  billing/
    CLAUDE.md
  web/
    CLAUDE.md

cd ~/work && claude

Claude can now read and edit every repo under work/. The top CLAUDE.md loads at launch. Each repo's own CLAUDE.md loads when Claude first reads a file in that repo, which is the behaviour the large codebases guide describes for a monorepo root. Run /context and look under Memory files to see which ones are loaded.

Three things to know:

This is the simplest setup, and it suits a team whose repos already sit in one folder.

Option 2: start in one repo and add the others

If most of the work is in one repo, start there and grant access to the rest.

cd ~/work/orders-api
claude --add-dir ../billing ../web

Inside a session, /add-dir <path> does the same. To make it permanent, set permissions.additionalDirectories in .claude/settings.json:

{
  "permissions": {
    "additionalDirectories": ["../billing", "../web"]
  }
}

Relative paths resolve against the directory you start Claude from. If you commit this file, each teammate gets the extra directories only after they trust the folder.

The catch is in the docs' own heading: additional directories grant file access, not configuration. Claude can read and edit the added repo, but whether that repo's instructions load depends on how you added it:

Added with Read and edit files Loads its CLAUDE.md and .claude/rules/ Loads its skills
additionalDirectories setting Yes Never Never
--add-dir flag or /add-dir command Yes Only with the environment variable below Yes

To load the added repo's CLAUDE.md as well:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../billing

The variable has no effect on directories listed in the setting. So the permanent, shareable way to add a repo is also the one that leaves its conventions out.

One more detail for teams that use several coding agents. From v2.1.277, Claude Code reads AGENTS.md when there is no CLAUDE.md in your working directory or above it. That does not extend to added directories: with the variable set, an added repo's CLAUDE.md loads and its AGENTS.md does not.

Write the map down

With ten repos open, Claude still has to work out which service owns the customer record and who calls whom, and it does that by reading files, which costs context. A short map at the top saves the search. Anthropic's article suggests the same thing where the folder structure does not explain itself: a short Markdown file, one line per top-level folder, that Claude can scan as a table of contents before it opens files.

In the parent CLAUDE.md, keep it to what applies everywhere:

# Repos in this workspace
- orders-api/  Go service. Owns orders. Publishes order.created to Kafka.
- billing/     Java service. Consumes order.created. Owns invoices.
- web/         Next.js front end. Calls orders-api over REST. Never calls billing.

# Rules for changes that cross repos
- Change the API contract in orders-api first, then the callers.
- One branch per repo, same branch name in each.

Three limits apply:

  • Target under 200 lines per CLAUDE.md file. The docs say longer files consume more context and reduce adherence.
  • @path/to/file imports work, to a depth of four hops, but imported files also load at launch, so splitting a long file does not make it cheaper. An import in a project file that points outside your working directory triggers an approval dialog the first time.
  • CLAUDE.md is context, not a control. The docs are direct: Claude treats it as "context, not enforced configuration". To block an action whatever Claude decides, use a PreToolUse hook.

Keep the searching out of your main session

A question such as "who calls this endpoint?" across several repos means a lot of grep output and file reads. Send it to a subagent. A subagent runs in its own context window and returns only a summary. The built-in Explore subagent is read-only and made for searching code. It skips your CLAUDE.md files, so name the repos and paths in the request:

Use a subagent to find every caller of POST /orders in ../web and ../billing.

For a change that touches several repos, the large codebases guide gives two pieces of advice: hand Claude the whole change in one session, and plan first in plan mode. Claude writes the plan to a file and Claude Code puts it back after each compaction, so the plan survives a long session even when the conversation history does not.

A code intelligence plugin connects Claude to a language server. Claude can then jump to a definition or list references without scanning the tree. The plugin needs the language server binary on each machine.

Option 3: MCP, for code that is not on your disk

Everything above assumes the repos are checked out next to each other. For an organisation with hundreds of repos, they are not. The route the docs point to is MCP: if you already run code search or a retrieval index, expose it as an MCP tool so Claude queries it instead of reading files.

To share a server with the team, add it at project scope:

claude mcp add --transport http code-search --scope project https://example.com/mcp

That writes .mcp.json in the project root, which the docs say to check into version control. In an interactive session, Claude Code asks for approval before it uses a server from that file. A server you want in all your projects goes in with --scope user.

Two limits apply. Claude Code warns when an MCP tool returns more than 10,000 tokens and sets a default maximum of 25,000. A larger text result is saved to a file for Claude to read, and you can raise the maximum with MAX_MCP_OUTPUT_TOKENS. And the answers are only as good as the service behind the server. Anthropic's article notes that an index built from embeddings can fall behind a busy codebase and return code that has since been renamed or deleted.

Where this stops

All of this works well for a handful of repos that one person can keep checked out. It gets harder as the number grows:

  • Claude only sees what is on the machine. A repo nobody cloned does not exist for the session, unless an MCP server describes it.
  • Search is paid for in context. With no index, every cross-repo question is answered by reading. Anthropic's own example is a vague pattern search across a billion-line codebase, which reaches the context limit before the work begins.
  • The map is hand-written. The large codebases guide says it of per-directory CLAUDE.md files: "Conventions drift, files go stale, and no one owns the root." Its fix is to move shared conventions into skills and into plugins that a platform team owns.
  • Instructions are not checks. A CLAUDE.md is context, so on its own it cannot stop a change that breaks another team's service. Blocking takes a hook, and a project's hooks load only from the folder you start in.

If the map needs to keep itself current

That last list is the problem we work on at StackRails. StackRails maps your code, architecture and policies across all your repos and updates the map on every commit. Claude Code reads it through a read-only MCP server, so the agent gets context for the task in front of it, including how other services connect, what depends on the code it is about to change, and which of your standards apply. The same server works with GitHub Copilot, Cursor and OpenAI Codex.

Your policies are then checked at three points: before the agent writes, on the developer's machine, and at the pull request. The details are on the platform page.