Claude Code Multi-Repo Workflows: Patterns That Scale (2026)

Claude Code is most teams' default coding agent in 2026, and that is exactly where the next problem starts. A single-repo setup is easy: one CLAUDE.md, one .claude/ folder, one MCP config, done. The moment you add a second repo, a shared component library, a backend service, an infra repo, a documentation site, the cracks show up. CLAUDE.md drifts. Sub-agents get copy-pasted and forked. MCP servers are duplicated in three places with three different versions. Nobody is sure which repo owns the linting skill.

The hard part is not Claude Code itself. The hard part is the boring infrastructure around it: how you share context, how you bundle code so the agent can reason across boundaries, how you keep skills in sync, and how you avoid paying for the same tokens twice. Most teams discover this after their second or third repo, when a refactor that should take an afternoon takes three days because the agent keeps "discovering" the same conventions from scratch.

This guide is the playbook we use at AY Automate when a client comes to us with five, ten, or thirty repos and asks "how do we make Claude Code work across all of these?" Six patterns, the tooling stack we actually run, real cost numbers, an onboarding sequence for new repos, and the failure modes that show up at scale.

When you actually need a multi-repo workflow

Not every team needs this. If you have one application repo and Claude Code does 90% of your editing inside it, you do not have a multi-repo problem, you have a single-repo workflow with occasional cross-cutting work. Resist the urge to over-engineer.

You need a real multi-repo workflow when at least two of the following are true:

• Claude Code regularly has to make changes that span more than one repo (a backend contract change that touches frontend, a shared types package that breaks consumers, an SDK update that ripples into examples).
• You maintain shared assets, sub-agents, skills, MCP servers, prompt templates, that more than one repo depends on.
• Different repos have different conventions and you keep watching the agent re-learn them from git log and stale READMEs.
• Onboarding a new engineer (or a new repo) to your Claude Code setup is now a multi-hour ritual instead of a 10-minute clone-and-go.
• Token spend is starting to matter, and you can see in your usage logs that the agent is re-reading the same files across sessions because each repo's context is isolated.

If you only check one box, hold off. If you check three or more, the patterns below will pay for themselves inside a sprint.

6 multi-repo patterns

1. Monorepo with one CLAUDE.md

When to use it. You control all the repos and there is no political reason to keep them separate. The teams working on them are either the same team or coordinate daily. The codebases share dependencies, deploy together, or release together.

How it works. Collapse everything into a single Turborepo or pnpm-workspaces monorepo. One root CLAUDE.md describes the overall architecture, naming conventions, and where each package lives. Each package gets a smaller, package-level CLAUDE.md that scopes the agent to that package's conventions. Claude Code automatically picks up nested CLAUDE.md files as it descends into a directory, so the agent always has the right context for the file it is editing.

Example. A SaaS product with apps/web, apps/api, packages/ui, packages/database, packages/auth. Root CLAUDE.md says "this is a Turborepo, use pnpm, all packages publish under @company/*, do not import across app boundaries." Each package's CLAUDE.md adds the specifics, packages/database says "use Drizzle, schema lives in src/schema, generate types with pnpm db:generate."

Why it scales. One source of truth. One .claude/ folder at the root. One MCP config. One set of sub-agents. The agent can reason about a backend change and the frontend consumer in the same session without you re-explaining the relationship. Costs drop because there is no duplication.

The downside is that not everything fits in a monorepo, especially if you have a public open-source library that you need to keep separate from a closed-source product.

2. Shared MCP server across repos

When to use it. You have multiple repos that all need to talk to the same set of external systems, your project management tool, your data warehouse, your design system docs, your internal RAG over architecture decisions. You do not want to install and configure the same MCP server in every repo.

How it works. Run the MCP server once, at the user level, in ~/.claude/mcp.json (or your team's equivalent). Every repo automatically inherits it. For team-wide servers, host the MCP server as a small internal service and point each developer's ~/.claude/mcp.json at the shared endpoint. For project-specific MCPs that should only run in one repo, override at the repo level with .mcp.json, Claude Code merges user and project configs, with project winning on key collisions.

Example. An AY Automate client with eight repos. Their ~/.claude/mcp.json registers a Linear MCP, a Notion MCP (for architecture docs), and a custom company-data MCP we built for them. Every repo gets the same three servers without any per-repo setup. The repo with the most sensitive data adds a .mcp.json that registers a fourth, scoped server for production database queries.

Gotcha. Centralizing MCP servers means a bad config update can break Claude Code across every repo at once. Version your MCP configs in a small internal repo and ship updates the same way you ship any other tool, with review.

3. Sub-agent library as separate repo

When to use it. You have written useful sub-agents, a security reviewer, a database migration auditor, a release-notes drafter, and you are tired of copy-pasting them between repos. Or worse, you have three slightly different versions of "code reviewer" in three repos and they have all drifted.

How it works. Create a dedicated repo, something like company/claude-agents, that holds your sub-agent definitions, prompts, and any supporting scripts. Each consumer repo either (a) symlinks .claude/agents/ to a cloned copy of the agents repo, (b) installs it as a git submodule, or (c), our preferred approach, uses a tiny setup-claude.sh script that clones the agents repo into .claude/agents/ on first run and updates it via a single command.

Example. A platform team maintaining company/claude-agents with twelve sub-agents. Every product repo runs ./scripts/setup-claude.sh after clone. Updates ship as PRs to the central repo. Consumers update by running ./scripts/setup-claude.sh --update. The platform team ships the same sub-agent improvements to forty repos in one PR.

Why it scales. Drift is the silent killer of multi-repo Claude Code setups. A central library forces every repo to converge on the same definition of "code reviewer" and the same expectations of what that agent will and will not do. When you want to upgrade your security agent because you learned something new from an incident, you ship one PR, not forty.

4. Cross-repo refactor with worktrees

When to use it. You need to make a coordinated change that touches multiple repos at once, usually because of an API contract change, a shared types update, or a rename that ripples through every consumer. Doing this with sequential cd repo-a && claude then cd repo-b && claude is slow and loses context between sessions.

How it works. Use git worktree to create parallel working copies of every affected repo under a single parent directory. Launch one Claude Code session at the parent and give it explicit context: "Here are five repos under this directory. The contract change is in repo-a/openapi.yaml. Update repo-b, repo-c, repo-d, and repo-e consumers to match." Claude Code can read across all the worktrees in one session.

Example. An SDK change in acme-sdk-ts that adds a required field to one method. We worktree acme-sdk-ts, acme-examples, acme-docs, and three internal consumers into a single ~/work/sdk-refactor/ directory. One Claude Code session, one shared plan, atomic commits in each repo, PRs opened in parallel. What would have been a half-day of context-switching becomes a 90-minute focused session.

Gotcha. Worktrees are not magic, they still need a coherent CLAUDE.md story. If your repos have wildly different conventions, the agent will trip. Pattern 5 helps here.

5. Repo-aware Claude Code via repomix bundles

When to use it. You need Claude Code in repo A to understand repo B without actually editing it. Common case: the frontend team wants the agent to reason about backend types and endpoints without pulling the backend repo into the workspace.

How it works. Use repomix (the de facto packaging tool in 2026) to bundle repo B into a single optimized file, typically repomix-output.xml or .md. Commit that bundle into repo A under .claude/context/backend.md, or fetch it on demand via a build step. Reference it in repo A's CLAUDE.md: "When you need to understand backend types, read .claude/context/backend.md. Do not modify backend code from this repo."

Example. A frontend repo whose CLAUDE.md says "API types are documented in .claude/context/api.md (auto-generated from acme-api repo on every backend release). Read it before adding a fetcher. Do not invent endpoints." The bundle is regenerated nightly by a GitHub Action that runs repomix against the backend repo and PRs the updated context file.

Why it scales. Read-only cross-repo awareness is dramatically cheaper than full multi-repo editing. The agent gets the context it needs without the surface area of accidentally editing the wrong codebase. Bundles are also a great cache, they are reusable across sessions, unlike on-the-fly file reads.

6. Shared agent skills repo

When to use it. Skills (the new pluggable knowledge packs in Claude Code) are becoming the unit of reuse in 2026. You have written a "release notes" skill, a "PR review" skill, a "database migration" skill, and you want every repo to use the same set, with the same updates.

How it works. Same shape as pattern 3, but for .claude/skills/ instead of .claude/agents/. Maintain a company/claude-skills repo. Each consumer either symlinks or copies the skills folder. Version skills like any other library, semver, changelog, release notes. Test skills against a benchmark repo before promoting them.

Example. Sixteen skills in a central repo: "write conventional commits", "audit Drizzle migrations", "run security review", "translate to French", "generate Storybook story", and so on. Every product repo at the company gets the same skills. When the platform team upgrades the "security review" skill after an incident, every repo benefits the next day.

Combination move. Patterns 3 and 6 work especially well together. We typically ship clients a company/claude-config repo that holds both agents and skills, with a setup script that drops them into any repo in 30 seconds. See our Claude Code team setup guide for the full playbook.

Tooling stack

Six patterns, four tools. Keep it lean.

repomix. The single most useful tool for multi-repo Claude Code work. It bundles a repository into a single optimized file that an agent can read in one shot, with sensible defaults for ignoring lockfiles, node_modules, generated artifacts, and binary blobs. We use it for pattern 5 (read-only cross-repo context), for onboarding (give the agent a complete view of a new repo in 30 seconds), and for any time you want to ship a "this is what this codebase looks like" file to a sub-agent.

Git worktrees. Native to git, no install needed. The cleanest way to have multiple repos open in one Claude Code session without symlink hacks or weird mount tricks. git worktree add ../worktree-name branch-name and you have a fully functioning working copy that shares the same .git directory. We worktree any time we need cross-repo edits.

Turborepo. Our default monorepo tool when consolidating into pattern 1. Excellent caching, sensible defaults for multi-package builds, great task graph. The turbo.json doubles as documentation for the agent, Claude Code reads it and figures out which packages depend on which.

pnpm workspaces. Pairs perfectly with Turborepo. Faster than npm or yarn, stricter about phantom dependencies (which means fewer surprises when the agent installs something in the wrong package), and the workspace protocol (workspace:*) is exactly the kind of explicit convention that helps an agent reason about internal dependencies.

You can add Nx, Lerna, or Rush if your team already runs them. The patterns work either way. What matters is that the tooling makes package boundaries explicit so the agent can reason about them.

Cost considerations for multi-repo work

Multi-repo work costs more than single-repo work, full stop. The agent has to load more context, reason about more relationships, and often re-reads files it already saw in a previous session because context windows do not persist between sessions. Here is how we keep costs sane in 2026:

Default to the fastest model that gets the job done, escalate only for hard reasoning. For multi-repo refactors where the agent is mostly applying a known transformation, a lighter, cheaper model is usually good enough. Save the more expensive, more capable model for the steps that genuinely need deeper reasoning.

Bundle, do not browse. A repomix bundle is one file read. An agent browsing a repo via repeated Read and Grep calls burns noticeably more tokens for the same understanding. Bundle anything the agent needs to read but not edit.

Cache aggressively. Claude Code's prompt caching gives you a meaningful discount on tokens that show up at the start of a session and persist. Put your CLAUDE.md, your skills, and your repomix bundles in positions where they get cached. Avoid editing CLAUDE.md mid-session. It busts the cache.

Worktree, do not duplicate. Worktrees share a .git directory, which means the agent does not pay to re-index history for every branch. Cheaper than cloning twice.

Watch for the usual cost leaks. The pattern we see most often behind a spike in token spend is a missing bundle (the agent re-reading a whole repo instead of a cached summary), a bloated CLAUDE.md that gets reloaded every session, or repeated full-repo scans that a narrower Read or Grep would have replaced. Our Claude Code agency audits this kind of thing regularly.

Onboarding new repos to your Claude Code setup

A new repo joins your stack. Here is the 10-minute onboarding sequence we use:

1. Clone the repo and run your setup script. The script clones (or updates) your central agents and skills repos into .claude/agents/ and .claude/skills/. If you do not have a setup script yet, write one, it is twenty lines of bash and it pays for itself the first time you onboard.

2. Generate a starter CLAUDE.md. Run Claude Code with a one-shot prompt: "Read the codebase, identify the stack, conventions, package boundaries, and write a CLAUDE.md that an unfamiliar agent could use to make safe changes." Review the output, edit, commit.

3. Add the repo to the central registry. We keep a small repos.json in our claude-config repo with metadata about every repo: name, stack, owners, whether it is in the worktree workspace, whether it ships a repomix bundle, where the bundle is published. This is the source of truth when running cross-repo operations.

4. Configure MCP. Decide whether the repo needs project-specific MCP servers on top of the user-level defaults. Add a .mcp.json if so. Common adds: a database MCP scoped to the repo's dev DB, a deployment MCP for the repo's specific platform.

5. Generate the first repomix bundle. If other repos need read-only awareness of this one, run repomix and commit the bundle to a location the consumers know about (often dist/context/{repo-name}.md in this repo, with a CI job that copies it to consumer repos on every release).

6. Run the validation pass. Open Claude Code, give it a small, real task (fix a typo, add a test, refactor a small function), and watch how it behaves. If it asks questions a good CLAUDE.md would have answered, update the CLAUDE.md and try again.

The whole sequence is 10 to 20 minutes per repo once you have done it twice. The first time takes an afternoon while you build the central pieces.

What breaks at scale

Past about 15 repos, new failure modes show up that did not exist at 3 or 5 repos. Expect them.

CLAUDE.md drift between similar repos. Two repos that should have nearly identical conventions develop subtle differences because the people maintaining them write CLAUDE.md slightly differently. Fix: introduce a "CLAUDE.md inheritance" pattern, a base CLAUDE.md in your central config, and each repo's CLAUDE.md says "extends @company/claude-config base; overrides below."

Sub-agent version skew. Some repos updated to the latest "code reviewer" sub-agent six months ago. Others are still on a forked, older copy. The agent's behavior is wildly inconsistent across repos. Fix: enforce the setup script as a CI check that fails if .claude/agents/ is out of date with the central repo.

MCP server contention. A team-wide MCP server that talks to your data warehouse becomes a bottleneck or a security concern when forty engineers are calling it through Claude Code. Fix: rate-limit per user, log queries, treat the MCP server like any production service.

Bundle staleness. repomix bundles get out of date because the regeneration job broke and nobody noticed. The agent confidently writes against stale types. Fix: include the bundle's git SHA at the top of every bundle file, and have a check that warns when the bundle is more than 7 days behind the source repo.

Cost explosion. A new engineer joins, runs Claude Code without understanding the patterns, and turns a workflow that should cost $0.50 into one that costs $40. Fix: usage dashboards per developer, and a written "how we use Claude Code here" page that lives in your onboarding docs. See also the best Claude Code workflows guide for tactics.

The "which agent edits this?" question. A bug surfaces. Was this code written by a human, the code-reviewer sub-agent, or a Claude Code session three weeks ago? Without provenance, post-mortems get harder. Fix: enforce commit message conventions that note when Claude Code is the author, and keep session logs (Claude Code already does this, surface them).

Closing CTA

If you are running Claude Code across more than a handful of repos and any of this sounds painful, you are not alone, it is the single most common gap we see in 2026 engineering orgs that adopted Claude Code aggressively in 2025. The patterns work. The tooling is mature. The cost is manageable. What is missing is usually a week of focused work to set up the central config, write the setup script, generate the first round of bundles, and standardize CLAUDE.md across repos.

AY Automate builds and ships exactly these setups for engineering orgs running 5 to 100+ repos. We bring the central config repo, the sub-agent library, the skills pack, the repomix pipeline, and the cost dashboards. Typical engagement is two weeks to a working multi-repo setup, plus ongoing maintenance if you want it. Book a consultation and bring a list of your repos and we will tell you which patterns fit and which you can skip.

FAQ

What is a Claude Code multi-repo workflow?

A multi-repo workflow is any setup where Claude Code reasons about, reads from, or edits more than one git repository in a coordinated way. It includes shared sub-agents, shared skills, cross-repo refactors, and read-only context bundles. The goal is to keep the agent coherent across repo boundaries instead of treating each repo as a completely isolated context.

Do I need a monorepo to use Claude Code at scale?

No. Monorepos are pattern 1 and they are great when you control the repos and want maximum sharing. But the other five patterns work fine across separate repos. Most clients we see run a hybrid, one or two monorepos for tightly-coupled products, plus a handful of separate repos for shared libraries, infra, and docs.

How do I share CLAUDE.md across repos without duplication?

Use the inheritance pattern: keep a base CLAUDE.md in a central claude-config repo, and have each consumer repo's CLAUDE.md reference it explicitly ("extends @company/claude-config base") plus add the repo-specific overrides. Claude Code does not natively resolve this, but a build step in your setup script can concatenate the base + the local file into the effective CLAUDE.md.

Is repomix the only way to bundle a repo for cross-repo context?

It is the dominant tool in 2026, but not the only one. Gitingest, code2prompt, and a few framework-specific bundlers (Next.js, FastAPI) also work. We standardize on repomix because the output is consistent across stacks and the ignore defaults are sensible. Whatever you pick, pick one and stick with it across repos.

How much does multi-repo Claude Code work cost compared to single-repo?

More, mostly from increased context size and repeated re-reads of files the agent already saw in an earlier session. The patterns above (bundles, worktrees, prompt caching) exist specifically to shrink that gap. Skip them and the agent re-reads everything from scratch every session, which is the single biggest driver of an unexpectedly large bill.

Should I use git submodules or a setup script to share sub-agents and skills?

Setup script. Submodules are technically cleaner but they confuse developers who have not used them, they break in subtle ways with CI, and they require an extra command at clone time. A 30-line bash script that clones or pulls the central repo into .claude/ is easier to maintain and easier to explain.

Can Claude Code edit multiple repos in one session safely?

Yes, via git worktrees (pattern 4). The agent treats each worktree as a separate directory and the underlying git operations stay isolated per repo. Commit per repo, open PRs per repo, do not let the agent create a single "mega-commit" that spans repos, that breaks the audit trail.

When should I hire help versus build this in-house?

Build in-house if you have a platform team with one or two people who can spend a week setting it up and an hour a week maintaining it. Hire help if you are an engineering org of 20+ developers with no platform team, or if you want to skip the learning curve and have a working setup in two weeks. Either way, the patterns above are the same, the only question is who builds them.