[{"data":1,"prerenderedAt":55},["ShallowReactive",2],{"blog-claude-code-multi-repo-projects":3,"blog-related-claude-code-multi-repo-projects":39},{"slug":4,"title":5,"description":6,"category":7,"categoryId":8,"keyword":9,"date":10,"minutes":11,"body":12,"html":13,"headings":14},"claude-code-multi-repo-projects","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.","Workflows","workflows","claude code multiple repositories","2026-11-17",5,"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.\n\n## How do you give Claude Code access to more than one repo?\n\nThree ways, from the permissions docs:\n\n```sh\n# 1. At startup\ncd ~\u002Fcode\u002Fshop-web\nclaude --add-dir ..\u002Fshop-api --add-dir ..\u002Fshop-shared\n\n# 2. During a session\n\u002Fadd-dir ..\u002Fshop-api\n\n# 3. Persistently, in .claude\u002Fsettings.json or settings.local.json\n{\n  \"permissions\": {\n    \"additionalDirectories\": [\"..\u002Fshop-api\", \"..\u002Fshop-shared\"]\n  }\n}\n```\n\nFiles in an added directory follow the same rules as the original one: reads need no prompt, and edits follow your current [permission mode](\u002Fblog\u002Fclaude-code-permission-modes). The session's primary working directory stays where you launched it, so that is where Claude's shell commands start.\n\nResuming does not remember added folders. When you run `claude --continue` or `claude --resume`, pass `--add-dir` again, including for directories you added with `\u002Fadd-dir`.\n\n## Parent folder or --add-dir: which should you use?\n\n```text\n~\u002Fcode\u002Fshop\u002F\n  shop-web\u002F\n  shop-api\u002F\n  shop-shared\u002F\n```\n\nLaunching from `~\u002Fcode\u002Fshop` 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\u002F` configuration is not the project configuration for the session.\n\nLaunching from one repo and adding the others keeps that repo's `.claude\u002Fsettings.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.\n\n## What loads from an added directory, and what does not?\n\nThis 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 `\u002Fadd-dir`:\n\n| Thing | Loaded from the added directory? |\n| --- | --- |\n| Skills in `.claude\u002Fskills\u002F` | Yes, with live reload |\n| Commands in `.claude\u002Fcommands\u002F` | Yes |\n| Subagents in `.claude\u002Fagents\u002F` | Yes |\n| `.claude\u002Fsettings.json` | Only `enabledPlugins` and `extraKnownMarketplaces` |\n| `CLAUDE.md`, `.claude\u002Frules\u002F`, `CLAUDE.local.md` | Only if `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` is set |\n\nSo by default the added repo's `CLAUDE.md` is not read. If each repo has conventions worth following, set the variable when you launch:\n\n```sh\nCLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ..\u002Fshop-api\n```\n\nDirectories 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\u002Fsettings.json` apply only after each teammate accepts the workspace trust dialog.\n\n## How do you write a CLAUDE.md for a multi-repo project?\n\nPut 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:\n\n```md\n# Shop (3 repos)\n\n- shop-web: Nuxt front end, `pnpm dev` on :3000\n- shop-api: Fastify API, `pnpm dev` on :4000, OpenAPI spec in `openapi.yaml`\n- shop-shared: TypeScript types published as `@shop\u002Fshared`\n\nWhen an API route changes: update `openapi.yaml`, regenerate types in\nshop-shared (`pnpm gen`), then fix callers in shop-web. Commit per repo.\n```\n\nKeep 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](\u002Fblog\u002Fclaude-md-guide) for the rest.\n\n## How do you make a change that touches two repos?\n\nAsk for the change as one task with an explicit order, and use [plan mode](\u002Fblog\u002Fclaude-code-plan-mode) first so you see which files in which repos it intends to touch:\n\n```text\nAdd a `currency` field to orders. Start in shop-api (route, schema,\nopenapi.yaml), regenerate shop-shared types, then update the order list in\nshop-web. Plan first; don't edit until I approve.\n```\n\nClaude can run git in a repo it is not launched in with `git -C ..\u002Fshop-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](\u002Fblog\u002Fclaude-code-commit-and-pull-requests), covers the mechanics.\n\n## What about worktrees across repos?\n\n`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 ..\u002Fshop-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](\u002Fblog\u002Fclaude-code-git-worktrees).\n\n## When is a monorepo or a single parent folder better?\n\nIf 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.\n\n## In Relais\n\nRelais 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](\u002Ffeatures).","\u003Cp>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 \u003Ccode>--add-dir\u003C\u002Fcode>. Which one you pick decides what configuration loads, so it is worth knowing the difference.\u003C\u002Fp>\n\u003Ch2 id=\"how-do-you-give-claude-code-access-to-more-than-one-repo\">\u003Ca class=\"anchor\" href=\"#how-do-you-give-claude-code-access-to-more-than-one-repo\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do you give Claude Code access to more than one repo?\u003C\u002Fh2>\n\u003Cp>Three ways, from the permissions docs:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"sh\">\u003Ccode># 1. At startup\ncd ~\u002Fcode\u002Fshop-web\nclaude --add-dir ..\u002Fshop-api --add-dir ..\u002Fshop-shared\n\n# 2. During a session\n\u002Fadd-dir ..\u002Fshop-api\n\n# 3. Persistently, in .claude\u002Fsettings.json or settings.local.json\n{\n  &quot;permissions&quot;: {\n    &quot;additionalDirectories&quot;: [&quot;..\u002Fshop-api&quot;, &quot;..\u002Fshop-shared&quot;]\n  }\n}\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Files in an added directory follow the same rules as the original one: reads need no prompt, and edits follow your current \u003Ca href=\"\u002Fblog\u002Fclaude-code-permission-modes\">permission mode\u003C\u002Fa>. The session&#39;s primary working directory stays where you launched it, so that is where Claude&#39;s shell commands start.\u003C\u002Fp>\n\u003Cp>Resuming does not remember added folders. When you run \u003Ccode>claude --continue\u003C\u002Fcode> or \u003Ccode>claude --resume\u003C\u002Fcode>, pass \u003Ccode>--add-dir\u003C\u002Fcode> again, including for directories you added with \u003Ccode>\u002Fadd-dir\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Ch2 id=\"parent-folder-or-add-dir-which-should-you-use\">\u003Ca class=\"anchor\" href=\"#parent-folder-or-add-dir-which-should-you-use\" aria-label=\"Link to this section\">#\u003C\u002Fa>Parent folder or --add-dir: which should you use?\u003C\u002Fh2>\n\u003Cpre class=\"code\" data-lang=\"text\">\u003Ccode>~\u002Fcode\u002Fshop\u002F\n  shop-web\u002F\n  shop-api\u002F\n  shop-shared\u002F\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Launching from \u003Ccode>~\u002Fcode\u002Fshop\u003C\u002Fcode> puts everything under one working directory with no flags. It is the simplest setup, and a \u003Ccode>CLAUDE.md\u003C\u002Fcode> in the parent can describe the layout. The costs: the parent is not a git repository, so \u003Ccode>git status\u003C\u002Fcode> there says nothing useful, and each repo&#39;s own \u003Ccode>.claude\u002F\u003C\u002Fcode> configuration is not the project configuration for the session.\u003C\u002Fp>\n\u003Cp>Launching from one repo and adding the others keeps that repo&#39;s \u003Ccode>.claude\u002Fsettings.json\u003C\u002Fcode>, hooks and skills as the project&#39;s, and treats the rest as extra reach. That suits &quot;mostly web, sometimes look at the API&quot;. Use the parent-folder layout when the work really is evenly spread.\u003C\u002Fp>\n\u003Ch2 id=\"what-loads-from-an-added-directory-and-what-does-not\">\u003Ca class=\"anchor\" href=\"#what-loads-from-an-added-directory-and-what-does-not\" aria-label=\"Link to this section\">#\u003C\u002Fa>What loads from an added directory, and what does not?\u003C\u002Fh2>\n\u003Cp>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 \u003Ccode>--add-dir\u003C\u002Fcode> or \u003Ccode>\u002Fadd-dir\u003C\u002Fcode>:\u003C\u002Fp>\n\u003Cdiv class=\"table-wrap\">\u003Ctable>\u003Cthead>\u003Ctr>\u003Cth>Thing\u003C\u002Fth>\u003Cth>Loaded from the added directory?\u003C\u002Fth>\u003C\u002Ftr>\u003C\u002Fthead>\u003Ctbody>\u003Ctr>\u003Ctd>Skills in \u003Ccode>.claude\u002Fskills\u002F\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>Yes, with live reload\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>Commands in \u003Ccode>.claude\u002Fcommands\u002F\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>Yes\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>Subagents in \u003Ccode>.claude\u002Fagents\u002F\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>Yes\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>.claude\u002Fsettings.json\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>Only \u003Ccode>enabledPlugins\u003C\u002Fcode> and \u003Ccode>extraKnownMarketplaces\u003C\u002Fcode>\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>CLAUDE.md\u003C\u002Fcode>, \u003Ccode>.claude\u002Frules\u002F\u003C\u002Fcode>, \u003Ccode>CLAUDE.local.md\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>Only if \u003Ccode>CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1\u003C\u002Fcode> is set\u003C\u002Ftd>\u003C\u002Ftr>\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Cp>So by default the added repo&#39;s \u003Ccode>CLAUDE.md\u003C\u002Fcode> is not read. If each repo has conventions worth following, set the variable when you launch:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"sh\">\u003Ccode>CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ..\u002Fshop-api\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Directories listed under \u003Ccode>permissions.additionalDirectories\u003C\u002Fcode> in a settings file are narrower still: they grant file access and load none of the above. And entries in a project&#39;s \u003Ccode>.claude\u002Fsettings.json\u003C\u002Fcode> apply only after each teammate accepts the workspace trust dialog.\u003C\u002Fp>\n\u003Ch2 id=\"how-do-you-write-a-claude-md-for-a-multi-repo-project\">\u003Ca class=\"anchor\" href=\"#how-do-you-write-a-claude-md-for-a-multi-repo-project\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do you write a CLAUDE.md for a multi-repo project?\u003C\u002Fh2>\n\u003Cp>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:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"md\">\u003Ccode># Shop (3 repos)\n\n- shop-web: Nuxt front end, `pnpm dev` on :3000\n- shop-api: Fastify API, `pnpm dev` on :4000, OpenAPI spec in `openapi.yaml`\n- shop-shared: TypeScript types published as `@shop\u002Fshared`\n\nWhen an API route changes: update `openapi.yaml`, regenerate types in\nshop-shared (`pnpm gen`), then fix callers in shop-web. Commit per repo.\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Keep it to what Claude cannot guess: where things live, how they connect, the order of a cross-repo change. See \u003Ca href=\"\u002Fblog\u002Fclaude-md-guide\">how to write a CLAUDE.md\u003C\u002Fa> for the rest.\u003C\u002Fp>\n\u003Ch2 id=\"how-do-you-make-a-change-that-touches-two-repos\">\u003Ca class=\"anchor\" href=\"#how-do-you-make-a-change-that-touches-two-repos\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do you make a change that touches two repos?\u003C\u002Fh2>\n\u003Cp>Ask for the change as one task with an explicit order, and use \u003Ca href=\"\u002Fblog\u002Fclaude-code-plan-mode\">plan mode\u003C\u002Fa> first so you see which files in which repos it intends to touch:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"text\">\u003Ccode>Add a `currency` field to orders. Start in shop-api (route, schema,\nopenapi.yaml), regenerate shop-shared types, then update the order list in\nshop-web. Plan first; don't edit until I approve.\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Claude can run git in a repo it is not launched in with \u003Ccode>git -C ..\u002Fshop-api status\u003C\u002Fcode>, or \u003Ccode>cd\u003C\u002Fcode> there inside a command; the docs note that a \u003Ccode>cd\u003C\u002Fcode> into an additional directory counts as read-only. Finish by asking Claude to run each repository&#39;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, \u003Ca href=\"\u002Fblog\u002Fclaude-code-commit-and-pull-requests\">commit, push and open a PR\u003C\u002Fa>, covers the mechanics.\u003C\u002Fp>\n\u003Ch2 id=\"what-about-worktrees-across-repos\">\u003Ca class=\"anchor\" href=\"#what-about-worktrees-across-repos\" aria-label=\"Link to this section\">#\u003C\u002Fa>What about worktrees across repos?\u003C\u002Fh2>\n\u003Cp>\u003Ccode>claude --worktree\u003C\u002Fcode> 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 \u003Ccode>git worktree add ..\u002Fshop-api-feature -b feature-x\u003C\u002Fcode> and add them with \u003Ccode>--add-dir\u003C\u002Fcode>, or you keep the feature small enough to do in one checkout at a time. Details in \u003Ca href=\"\u002Fblog\u002Fclaude-code-git-worktrees\">git worktrees with Claude Code\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch2 id=\"when-is-a-monorepo-or-a-single-parent-folder-better\">\u003Ca class=\"anchor\" href=\"#when-is-a-monorepo-or-a-single-parent-folder-better\" aria-label=\"Link to this section\">#\u003C\u002Fa>When is a monorepo or a single parent folder better?\u003C\u002Fh2>\n\u003Cp>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 \u003Ccode>CLAUDE.md\u003C\u002Fcode> removes most of the daily pain.\u003C\u002Fp>\n\u003Ch2 id=\"in-relais\">\u003Ca class=\"anchor\" href=\"#in-relais\" aria-label=\"Link to this section\">#\u003C\u002Fa>In Relais\u003C\u002Fh2>\n\u003Cp>Relais calls this a group: a project&#39;s ordered list of folders. The first folder is the session&#39;s working directory and the others are passed to Claude Code as additional directories; it also sets \u003Ccode>CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1\u003C\u002Fcode>, so each folder&#39;s \u003Ccode>CLAUDE.md\u003C\u002Fcode> 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&#39;s views, or start a session in a subfolder, while Claude still reaches them. See \u003Ca href=\"\u002Ffeatures\">features\u003C\u002Fa>.\u003C\u002Fp>\n",[15,18,21,24,27,30,33,36],{"id":16,"text":17},"how-do-you-give-claude-code-access-to-more-than-one-repo","How do you give Claude Code access to more than one repo?",{"id":19,"text":20},"parent-folder-or-add-dir-which-should-you-use","Parent folder or --add-dir: which should you use?",{"id":22,"text":23},"what-loads-from-an-added-directory-and-what-does-not","What loads from an added directory, and what does not?",{"id":25,"text":26},"how-do-you-write-a-claude-md-for-a-multi-repo-project","How do you write a CLAUDE.md for a multi-repo project?",{"id":28,"text":29},"how-do-you-make-a-change-that-touches-two-repos","How do you make a change that touches two repos?",{"id":31,"text":32},"what-about-worktrees-across-repos","What about worktrees across repos?",{"id":34,"text":35},"when-is-a-monorepo-or-a-single-parent-folder-better","When is a monorepo or a single parent folder better?",{"id":37,"text":38},"in-relais","In Relais",[40,45,50],{"slug":41,"title":42,"description":43,"category":7,"categoryId":8,"keyword":44,"date":10,"minutes":11},"claude-code-commit-and-pull-requests","Commit, push and open a pull request with Claude Code","How to have Claude Code write commit messages, push a branch and open a PR with gh: prompts that work, permission rules, attribution settings and checks.","claude code commit and pull request",{"slug":46,"title":47,"description":48,"category":7,"categoryId":8,"keyword":49,"date":10,"minutes":11},"claude-code-git-worktrees","Git worktrees with Claude Code: parallel features, no conflicts","Run Claude Code in a git worktree with one flag: separate branches, no stepping on each other's files. Setup, cleanup, base branches and the gotchas.","claude code git worktrees",{"slug":51,"title":52,"description":53,"category":7,"categoryId":8,"keyword":54,"date":10,"minutes":11},"undo-claude-code-changes","How to undo what Claude Code changed: \u002Frewind and git","Undo Claude Code's edits with \u002Frewind, git restore and reflog. What checkpoints cover, what they miss (bash, subagents), and habits that make undo painless.","undo claude code changes",1794931098788]