Claude Code across several repositories: --add-dir and layouts

How to work with Claude Code on a project split across repos: launch from a parent folder, --add-dir, what config loads from extra folders, and commits.

· 5 min read

Claude Code starts in one folder and can read and edit files there. To work on a project that spans several repositories (an API, a web app, a shared library), either start it in a parent folder that contains them, or start it in one repo and add the others with --add-dir. Which one you pick decides what configuration loads, so it is worth knowing the difference.

#How do you give Claude Code access to more than one repo?

Three ways, from the permissions docs:

# 1. At startup
cd ~/code/shop-web
claude --add-dir ../shop-api --add-dir ../shop-shared

# 2. During a session
/add-dir ../shop-api

# 3. Persistently, in .claude/settings.json or settings.local.json
{
  "permissions": {
    "additionalDirectories": ["../shop-api", "../shop-shared"]
  }
}

Files in an added directory follow the same rules as the original one: reads need no prompt, and edits follow your current permission mode. The session's primary working directory stays where you launched it, so that is where Claude's shell commands start.

Resuming does not remember added folders. When you run claude --continue or claude --resume, pass --add-dir again, including for directories you added with /add-dir.

#Parent folder or --add-dir: which should you use?

~/code/shop/
  shop-web/
  shop-api/
  shop-shared/

Launching from ~/code/shop puts everything under one working directory with no flags. It is the simplest setup, and a CLAUDE.md in the parent can describe the layout. The costs: the parent is not a git repository, so git status there says nothing useful, and each repo's own .claude/ configuration is not the project configuration for the session.

Launching from one repo and adding the others keeps that repo's .claude/settings.json, hooks and skills as the project's, and treats the rest as extra reach. That suits "mostly web, sometimes look at the API". Use the parent-folder layout when the work really is evenly spread.

#What loads from an added directory, and what does not?

This is the part that trips people up. An added directory grants file access, not a full configuration root. From the permissions docs, for directories added with --add-dir or /add-dir:

ThingLoaded from the added directory?
Skills in .claude/skills/Yes, with live reload
Commands in .claude/commands/Yes
Subagents in .claude/agents/Yes
.claude/settings.jsonOnly enabledPlugins and extraKnownMarketplaces
CLAUDE.md, .claude/rules/, CLAUDE.local.mdOnly if CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 is set

So by default the added repo's CLAUDE.md is not read. If each repo has conventions worth following, set the variable when you launch:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shop-api

Directories listed under permissions.additionalDirectories in a settings file are narrower still: they grant file access and load none of the above. And entries in a project's .claude/settings.json apply only after each teammate accepts the workspace trust dialog.

#How do you write a CLAUDE.md for a multi-repo project?

Put a short map in the file Claude reads at the start of every session, whichever repo it is launched from. Things that earn their lines:

# Shop (3 repos)

- shop-web: Nuxt front end, `pnpm dev` on :3000
- shop-api: Fastify API, `pnpm dev` on :4000, OpenAPI spec in `openapi.yaml`
- shop-shared: TypeScript types published as `@shop/shared`

When an API route changes: update `openapi.yaml`, regenerate types in
shop-shared (`pnpm gen`), then fix callers in shop-web. Commit per repo.

Keep it to what Claude cannot guess: where things live, how they connect, the order of a cross-repo change. See how to write a CLAUDE.md for the rest.

#How do you make a change that touches two repos?

Ask for the change as one task with an explicit order, and use plan mode first so you see which files in which repos it intends to touch:

Add a `currency` field to orders. Start in shop-api (route, schema,
openapi.yaml), regenerate shop-shared types, then update the order list in
shop-web. Plan first; don't edit until I approve.

Claude can run git in a repo it is not launched in with git -C ../shop-api status, or cd there inside a command; the docs note that a cd into an additional directory counts as read-only. Finish by asking Claude to run each repository's own test command, one repo at a time, and to report which commands it ran and what they printed; a cross-repo change that passes only in the repo you were looking at is the usual failure. For commits, keep them per repository and in dependency order: shared first, then the API, then the web app. A commit in one repo cannot include files from another, so you will make two or three small commits, not one. The next article, commit, push and open a PR, covers the mechanics.

#What about worktrees across repos?

claude --worktree creates a worktree of the repository you launched in only. For a cross-repo feature you either create a worktree in each repo yourself with git worktree add ../shop-api-feature -b feature-x and add them with --add-dir, or you keep the feature small enough to do in one checkout at a time. Details in git worktrees with Claude Code.

#When is a monorepo or a single parent folder better?

If you change the API and the client together every week, the friction of three repos is real: three branches, three PRs, an ordering problem. Claude Code will cope, but your CI and your reviewers have the same problem. Moving to a monorepo is a team decision, not a Claude Code one. In the meantime, a parent-folder launch with a good CLAUDE.md removes most of the daily pain.

#In Relais

Relais calls this a group: a project's ordered list of folders. The first folder is the session's working directory and the others are passed to Claude Code as additional directories; it also sets CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1, so each folder's CLAUDE.md loads. The Changes tab lists what is uncommitted in each repository of the group with its branch and the commits to pull and push, so a cross-repo change is reviewed in one place. You can hide folders from the app's views, or start a session in a subfolder, while Claude still reaches them. See features.

Claude Code,
better organized.

$14.99 a month, everything included. Mac and Linux, on your Claude Pro or Max plan. Cancel any time.