Claude Code with multiple repos: --add-dir and /add-dir

Claude Code works on multiple repositories in one session when you add them as working directories. Start in one repository and run claude --add-dir ../api ../web, or type /add-dir ../api mid-session. Claude can then read and edit files in every added folder, under the same permission rules as the first one.

What surprises people is what it doesn't do. An added directory gives Claude its files, not its setup: its CLAUDE.md, hooks and MCP servers stay behind unless you ask for them. The details below are from Anthropic's permissions page and CLI reference, read on 23 October 2026.

Three ways to add a repository#

The flag takes several paths at once (claude --add-dir ../apps ../lib) and checks that each one exists. Most network paths are refused, such as a Windows share \\server\share; map it to a drive letter and pass the drive at launch instead.

To keep a set of repositories every time, put them in the project's settings:

{
  "permissions": {
    "additionalDirectories": ["../api", "../shared-types"]
  }
}

That file route grants file access and nothing else, which is often what you want for a folder Claude only needs to read.

What an added directory loads, and what it doesn't#

Anthropic's rule is "additional directories grant file access, not configuration". A few kinds of configuration are loaded as exceptions, and only for folders added with --add-dir or /add-dir:

Hooks and settings come from the folder you started in, plus your user settings and managed settings. So start Claude Code in the repository whose rules should govern the work. Usually that's the one you will commit to most.

Should the other repository's CLAUDE.md load?#

Turn it on when the second repository has conventions Claude must follow while editing there, such as a different test command, a different code style or generated files to leave alone:

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

Leave it off when you only need Claude to read the other repository, for example to look up a type or an endpoint. Its instructions would then sit in context without a job to do. If the two repositories disagree, say in your starting CLAUDE.md which one wins. Our CLAUDE.md guide has more on what belongs in that file, and AGENTS.md vs CLAUDE.md on sharing one file between agents.

Coming back to a multi-repo session#

claude --continue and the --resume picker both include sessions that added the current directory with /add-dir. So a session started in web that added api is found again from either folder.

/cd <path> is different: it moves the session's main directory instead of adding one. Claude Code keeps the conversation, loads the new folder's CLAUDE.md, settings, hooks and project MCP servers, and keeps the directories you added with --add-dir or /add-dir.

One session over many repositories, or one per repository?#

One session across repositories suits a change that has to land in step: an API field and the client that reads it, a shared type and its users. Claude sees both sides at once and can keep them in agreement.

Separate sessions suit work that only touches one repository at a time, or a change you want to review and merge per repository. Each has its own folder and its own history, and none can wander into another's files. On a large monorepo the questions are different; our large codebase guide covers those. When you run several sessions side by side, running Claude Code agents in parallel explains how to keep them apart with worktrees. For unrelated projects, each with its own settings, CLAUDE.md and MCP servers, see Claude Code across many projects.

How Shuriken splits the work#

Shuriken is built around the second road. A project in Shuriken is one folder on one of your computers or servers. Every chat in it except the project's Main chat works on its own branch in its own git worktree, so two chats never edit the same checkout. Add each repository as its own project and every chat lands on its own, with Finish or a pull request: the per-repository review described above.