Claude Code Across Multiple Repositories

Claude Code multi repo work means running one agent across several codebases, either a true monorepo, a set of sibling repos in one workspace folder, or independent repos you jump between during the same task. This comes up constantly for engineers who own a frontend, a backend, and a shared package, or who maintain a service and its infra repo side by side. The short answer: Claude Code handles this well if you give it the right working directory, the right memory files, and the right isolation strategy for parallel changes. The rest of this article covers exactly how.

If you have only used Claude Code inside a single git repository, the jump to multi repo work raises real questions. Does it read files outside the current directory. Does CLAUDE.md apply across projects. Can two Claude Code sessions safely touch two repos at once without stepping on each other. Can one session make a coordinated change across repos, like bumping a shared library version and updating every consumer. All of this is answered below with working configuration and commands.

Why multi repo work is different from single repo work

A single repo session is simple: you cd into the project, Claude Code reads the local CLAUDE.md, and every file operation is scoped to that tree. Multi repo work breaks that simplicity in three ways.

First, context boundaries get fuzzy. If your workspace folder has three repos as siblings, an agent exploring "the codebase" might wander into a repo it should not touch, or miss the fact that a file it needs lives one directory up and over.

Second, coordinated changes need commit discipline per repo. A change that spans a backend and a frontend repo is really two separate commits (and probably two separate PRs), not one. Claude Code does not automatically know that a diff needs to be split along repo boundaries unless you tell it.

Third, parallel work needs isolation. If you want Claude Code to work on repo A while you manually work on repo B, or you want two Claude Code sessions each iterating on a different feature in the same repo, you need separate working trees so file edits and git state do not collide.

None of these are blockers. They are workspace layout and process decisions you make once and then reuse.

Set up a workspace root that reflects reality

Start by deciding whether your multi repo setup is really a monorepo (one git root, multiple packages) or a polyrepo (multiple git roots as sibling folders). The right Claude Code setup differs for each.

For a monorepo:

my-company/
  .git/
  CLAUDE.md
  packages/
    api/
      CLAUDE.md
    web/
      CLAUDE.md
    shared/
      CLAUDE.md

For a polyrepo workspace, each project keeps its own .git:

workspace/
  CLAUDE.md          <- describes the workspace, not a repo
  api/
    .git/
    CLAUDE.md
  web/
    .git/
    CLAUDE.md
  infra/
    .git/
    CLAUDE.md

Claude Code reads CLAUDE.md files hierarchically starting from your current directory and walking up. In the polyrepo layout above, if you launch Claude Code from inside workspace/api, it picks up api/CLAUDE.md and the parent workspace/CLAUDE.md, but not web/CLAUDE.md or infra/CLAUDE.md. That is usually what you want: repo-specific instructions stay scoped to that repo, and the workspace-level file carries only cross-cutting facts, like "web calls api's REST endpoints under /v1" or "infra provisions the database api depends on."

Write the workspace root CLAUDE.md as a map, not a manual. State what each subfolder is, which repo owns which concern, and point to the folder-specific CLAUDE.md for details. Keep it short. A workspace map that tries to hold every rule for every repo becomes stale the moment one repo changes, and stale instructions are worse than no instructions because the agent trusts them.

Launching Claude Code with the right working directory

The working directory you launch from determines what Claude Code treats as "local." Two patterns cover almost every case.

Launch from the specific repo when the task is scoped to one project:

cd workspace/api
claude

This keeps file reads, git operations, and CLAUDE.md discovery scoped to api. It is the right default for day to day work: fix a bug in the API, add a test to the web app, update infra config. One task, one repo, one working directory.

Launch from the workspace root when the task genuinely spans repos:

cd workspace
claude

From here, Claude Code can read across all sibling repos in the same conversation, useful for tasks like "the api repo changed its response shape for /v1/users, update the web repo's TypeScript types and any components that destructure the old shape." Be explicit in your prompt about which repo each part of the task belongs to, and expect Claude Code to run separate git commands (status, diff, commit) per repo since each has its own .git.

A pattern worth adopting: when you ask for a cross repo change from the workspace root, ask for two separate commits explicitly, one per repo, rather than letting the agent guess. "Commit the api change in api/ with its own message, then commit the web change in web/ with its own message" removes ambiguity and keeps your git history clean per project.

Using CLAUDE.md to prevent cross repo bleed

The most common failure mode in multi repo Claude Code work is instruction bleed: a rule meant for one repo gets applied to another because it was written at too high a level, or because the agent read a neighboring CLAUDE.md it should not have needed.

Three habits fix this:

Scope rules to the folder they apply to. If api/ uses Postgres and web/ uses none, the database connection rules belong in api/CLAUDE.md, not the workspace root. Test this by asking: if I deleted every other repo and kept just this one, would this instruction still make sense? If not, it belongs at the workspace level or is misplaced.

Name repos explicitly in workspace-level instructions. Instead of "run tests before committing," write "in api/, run npm test; in web/, run npm run test:unit." Ambiguous instructions at the workspace level get applied inconsistently because the agent has to guess which repo's tooling you mean.

Keep an explicit "do not touch" list when relevant. If your workspace root includes a repo that is read-only from this machine, e.g. a vendored dependency or a repo owned by another team, say so directly: "Never edit files under vendor/, it is a read-only mirror." This is far more reliable than hoping the agent infers it from folder naming.

Parallel sessions and git worktrees

Running two Claude Code sessions against the same repo at the same time, or wanting to keep an in-progress agent change isolated from your own manual edits, needs process-level isolation, not just prompt discipline. Two file edit streams hitting the same working tree at once will corrupt each other's changes and confuse git status.

Git worktrees are the standard fix. A worktree gives you a second working directory backed by the same repository, checked out to its own branch, so two processes can operate simultaneously without collision:

cd workspace/api
git worktree add ../api-feature-x feature-x

Now workspace/api stays on its current branch for your own work, and workspace/api-feature-x is a fully separate directory on branch feature-x where a Claude Code session can run independently:

cd workspace/api-feature-x
claude

This is the right approach any time you want to parallelize: one session refactoring a module while another session writes tests, or one session on a hotfix branch while your main working tree stays on a feature branch. Each worktree has its own file state; commits made in one do not touch the files in another until you merge or push and pull.

Clean up worktrees once the branch is merged or abandoned, otherwise they accumulate and clutter git worktree list:

git worktree remove ../api-feature-x

For polyrepo workspaces with several projects, apply the same pattern per repo that needs parallel work. There is no cross repo worktree primitive, worktrees are a per git-root concept, so a task that touches two repos in parallel needs a worktree set up in each.

Coordinated changes: bumping a shared dependency

A concrete example ties this together. Say shared is a package published from your monorepo (or a separate repo consumed by both api and web), and you need to change its exported function signature, then update every call site.

From the workspace or monorepo root, the prompt should name the sequence explicitly:

1. In packages/shared, update the `formatCurrency` function to accept a
   currency code parameter, defaulting to "USD" for backward compatibility.
2. In packages/api, find every call to formatCurrency and update the ones
   that handle non-USD amounts to pass the correct currency code.
3. In packages/web, do the same.
4. Run each package's test suite separately and report results per package.
5. Do not commit yet, show me a diff summary first.

Breaking the task into per-package steps, even inside a single monorepo, keeps Claude Code's search and edit scope tight. It reduces the chance of an edit landing in the wrong package, and it gives you a natural checkpoint to review before committing. The "do not commit yet" instruction matters more in multi repo or multi package work than single repo work, because the blast radius of an unreviewed cross cutting change is larger.

For a true polyrepo (separate git roots), the same sequence applies, just with an explicit note that the shared package's new version needs to be bumped and republished before api and web can pick it up, since there is no live filesystem link between them the way there is inside a monorepo's node_modules workspace links.

Keeping context from ballooning

Multi repo sessions burn context faster because there is more to read. Two adjustments help.

Ask for targeted reads instead of open ended exploration. "Look at packages/api/src/routes/users.ts and packages/web/src/api/users.ts" gets to the relevant files directly, versus "figure out how the users API works across the codebase," which triggers broad search across every repo in the workspace.

Close out finished repo work explicitly before moving to the next repo in the same conversation. If you just finished a multi step change in api and are about to start unrelated work in web, say so: "That api work is done and committed. Now, separately, in web..." This gives the agent a clean signal to stop carrying api-specific context forward, which keeps its reasoning focused on the repo actually in front of it.

For long running multi repo work, consider splitting into separate Claude Code sessions per repo rather than one marathon session that touches everything. A session scoped to api with api/CLAUDE.md loaded and nothing else tends to produce tighter, more predictable changes than a workspace-root session juggling three repos' worth of conventions at once. Reserve the workspace-root session for the coordination step: planning the cross repo change and reviewing the final diffs, not for grinding through every file edit.

A workflow that holds up in practice

Combining everything above into a repeatable pattern:

• Keep a short workspace root CLAUDE.md that maps repos to responsibilities and points to their own CLAUDE.md files, nothing more.
• Default to launching Claude Code from inside the specific repo for scoped work.
• Launch from the workspace root only for genuinely cross repo tasks, and be explicit about per repo commits.
• Use git worktrees whenever you need parallel edit streams, whether that is two Claude Code sessions or an agent session running alongside your own manual work.
• Break multi repo prompts into ordered, per repo steps rather than one broad instruction, and ask for a diff review before committing.
• Split unrelated multi repo work into separate sessions instead of one long session that drags context from repo to repo.

FAQ

Does Claude Code read CLAUDE.md files from sibling repos automatically? No. CLAUDE.md discovery walks up from your current working directory through parent folders. If you launch from inside one repo in a polyrepo workspace, sibling repos' CLAUDE.md files are not automatically loaded unless the workspace root itself has one that Claude Code encounters while walking up.

Can one Claude Code session safely edit two different git repos in the same conversation? Yes, as long as you launch it from a working directory that contains both (like a workspace root with repos as subfolders) and you ask for separate git operations per repo. Each repo keeps its own git history; there is no merged git state between sibling repos.

Is a monorepo or polyrepo easier for Claude Code to work with? Neither is strictly easier; the deciding factor is how well scoped your CLAUDE.md files are. A well organized polyrepo with clear per-repo instructions works as smoothly as a monorepo with well organized package folders. A monorepo with one giant undifferentiated CLAUDE.md at the root is harder to work with than either.

Do I need git worktrees for every multi repo task? No. Worktrees matter when you need true parallelism, two processes editing the same repo's working tree at the same time. Sequential work in one repo at a time, even across a multi repo workspace, does not need worktrees.

What happens if I ask for a cross repo change without specifying per repo commits? Claude Code will typically still figure out that each repo needs its own commit, since git operations are inherently scoped to whichever .git directory is active for a given file. But being explicit avoids ambiguity, especially when the change also touches shared config files that might sit at the workspace root outside any repo.

Can I use Claude Code to keep a shared package version in sync across repos? Yes, but treat it as a two-step process: update and publish the shared package first (in its own repo or package), then update consumers to pull the new version. Ask Claude Code to do these as separate, reviewed steps rather than one combined change, since publishing typically involves a version bump and a registry push that you want to confirm before consumers depend on it.