Agents Across Multiple Repositories

Some projects aren't one big repo with subfolders - they're several genuinely separate repositories (an API here, a client there) that still need coordinated changes.

The counterpart to a monorepo

The monorepo entry covers one repository with many subprojects under a shared root - one CLAUDE.md tree, one git history. Multi-repo is the opposite: separate repositories, each with its own history and versioning, still needing to change together - an API repo and a frontend client, say, or a shared library pulled into downstream projects.

Context per repo

Each repo gets its own context, its own CLAUDE.md, its own conventions. A monorepo solves this with layered files under one root; multi-repo keeps things separate simply because the repos live apart.

Coordinating a change that spans repos

A single logical change - adding a field to an API response and updating the client that uses it - touches two repos with separate histories. You work on both in one session, keeping straight which change belongs to which repo's history and PR.

Merge order matters

If the client depends on the new field, deploying it before the API ships breaks things - it would call an endpoint that doesn't return that field yet. The API side needs to land and deploy first, the client following once it's live.

Versioning across the boundary

Once two repos are separate, one depends on the other through a versioned interface, not git-lockstep - a package version, an API tag, a schema version - letting each release on its own schedule while staying explicit about what works together.

EXAMPLE

Cross-repo change: adding a "lastLoginAt" field to a user API response, consumed by a separate web client. Step 1 - API repo (separate git history, own CI/CD): - Add the field to the response schema (additive, doesn't break existing clients that ignore unknown fields). - Update API tests, get it reviewed, merge, deploy. - Tag or version-bump the API (e.g. v2.4.0) so the client repo has something concrete to depend on. Step 2 - client repo (once v2.4.0 is actually live): - Update the type definitions / API client to expect the new field. - Add the UI that displays it. - Bump the client's pinned API version dependency, if it tracks one explicitly. Session setup for working on step 2 while referencing step 1's actual shape: claude --add-dir ../api-repo (lets the agent read the API repo's updated schema/tests as ground truth while editing only the client repo) What NOT to do: write both changes in the same sitting and merge them together assuming simultaneous deploy - if the client ships first, it calls a field that doesn't exist yet in production.

🛠️ EXERCISE — TRY IT YOURSELF

Plan a cross-repo change end-to-end, from merge order to version boundary, without writing any code.

Pick (or imagine) two separate repos with a real dependency, like an API and a client, or a shared library and a project using it.
Write down one small feature that requires a change in both.
Decide and write down the merge order: which repo needs to land and ship first, and why.
Decide how the dependent repo will reference the specific version/state it depends on (a version bump, a tag, a pinned commit).
Write the two-step plan as if briefing another engineer: what happens in repo A first, what happens in repo B only afterward.

✅ SELF-CHECK

☐ Would your plan actually work if repo A's change was merged but not yet deployed when repo B's change went out - or does your plan implicitly assume simultaneous deploy?
☐ Does your dependent repo reference a concrete version/tag of the other, or does it just assume 'whatever's currently on the main branch'?

QUICK QUIZ

What's the key structural difference between the multi-repo pattern described here and the monorepo pattern?