# Claude Code with multiple repos: --add-dir and /add-dir > One Claude Code session over multiple repositories: --add-dir gives Claude a second repo's files, not its CLAUDE.md, hooks or MCP servers. The setup. Source: https://shuriken.sh/guides/claude-code-multiple-repositories One Claude Code session over multiple repositories: --add-dir gives Claude a second repo's files, not its CLAUDE.md, hooks or MCP servers. The setup. By Shuriken Updated 27 October 2026 3 min read **Contents** 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](https://code.claude.com/docs/en/permissions) and [CLI reference](https://code.claude.com/docs/en/cli-reference), read on 23 October 2026. ## Three ways to add a repository # | How | When it applies | Loads skills, commands, subagents | | --- | --- | --- | | claude --add-dir [more paths] | This session, from the start | Yes | | /add-dir | This session, from now on | Yes | | permissions.additionalDirectories in a settings file | Every session that reads that file | No, file access only | 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: json { "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: | From the added repository | Loaded? | | --- | --- | | Skills in .claude/skills/ | Yes, with live reload | | Commands in .claude/commands/ | Yes. If both define one with the same name, your starting project's wins | | Subagents in .claude/agents/ | Yes | | .claude/settings.json | Only enabledPlugins and extraKnownMarketplaces | | CLAUDE.md , .claude/rules/ , CLAUDE.local.md | Only with CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 | | Hooks, other settings, .mcp.json servers | No | 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: bash 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](https://shuriken.sh/guides/claude-md-best-practices) has more on what belongs in that file, and [AGENTS.md vs CLAUDE.md](https://shuriken.sh/compare/agents-md-vs-claude-md) on sharing one file between agents. In Shuriken a chat can work on its own branch in its own worktree, and Finish merges it after your checks. [Download](https://shuriken.sh/download) ## 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 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](https://shuriken.sh/guides/claude-code-large-codebase) covers those. When you run several sessions side by side, [running Claude Code agents in parallel](https://shuriken.sh/guides/run-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](https://shuriken.sh/guides/claude-code-multiple-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. Share [X](https://x.com/intent/post?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fclaude-code-multiple-repositories&text=Claude%20Code%20with%20multiple%20repos%3A%20--add-dir%20and%20%2Fadd-dir)[LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fclaude-code-multiple-repositories)[Hacker News](https://news.ycombinator.com/submitlink?u=https%3A%2F%2Fshuriken.sh%2Fguides%2Fclaude-code-multiple-repositories&t=Claude%20Code%20with%20multiple%20repos%3A%20--add-dir%20and%20%2Fadd-dir)[Reddit](https://www.reddit.com/submit?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fclaude-code-multiple-repositories&title=Claude%20Code%20with%20multiple%20repos%3A%20--add-dir%20and%20%2Fadd-dir)[E-mail](mailto:?subject=Claude%20Code%20with%20multiple%20repos%3A%20--add-dir%20and%20%2Fadd-dir&body=https%3A%2F%2Fshuriken.sh%2Fguides%2Fclaude-code-multiple-repositories) ## Sources - [Configure permissions: working directories and additional directories (Claude Code docs)](https://code.claude.com/docs/en/permissions) (accessed 23 October 2026) - [CLI reference: --add-dir, --continue and --resume (Claude Code docs)](https://code.claude.com/docs/en/cli-reference) (accessed 23 October 2026) ## Frequently asked questions **Can Claude Code work on two repositories at once?** Yes. Start it in one and add the other with claude --add-dir ../other-repo, or run /add-dir ../other-repo during the session. Claude can then read and edit files in both. **Does --add-dir load the other repository's CLAUDE.md?** Not by default. Set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 and Claude Code also loads CLAUDE.md, .claude/rules/ and CLAUDE.local.md from directories added with --add-dir or /add-dir. **How do I add a directory permanently in Claude Code?** List it under permissions.additionalDirectories in a settings file. That grants file access only: unlike --add-dir, it loads no skills, commands, subagents or CLAUDE.md from that directory. **Do hooks and MCP servers from an added directory load?** No. Hooks and most settings load from the directory you started in, your user settings and managed settings. From an --add-dir directory Claude Code loads skills, commands, subagents, and only the enabledPlugins and extraKnownMarketplaces settings. Parallel agents Agents side by side, each on its own branch if you want. A new chat gets its own branch and worktree unless you pick the project folder, so agents don't step on each other. Finish runs your checks and merges each one back. [Download](https://shuriken.sh/download) [Other platforms](https://shuriken.sh/download#main) ## Keep reading - [Run multiple Claude Code sessions in tmux: Guide 27 Oct 2026 3 min read Run several Claude Code sessions side by side in tmux, each in its own git worktree, and keep them running after you close the terminal. Commands included.](https://shuriken.sh/guides/claude-code-tmux-multiple-sessions) - [Claude Code --worktree: built-in worktrees, explained: Guide 27 Oct 2026 8 min read claude -w makes a Claude Code worktree at .claude/worktrees/ on branch worktree-. On exit it asks before deleting any work.](https://shuriken.sh/guides/claude-code-worktree-flag) - [Codex worktrees: run several Codex agents in parallel: Guide 27 Oct 2026 7 min read Codex app: pick Worktree under the composer. Codex CLI: run codex --worktree (0.156.0 or later). Each chat gets its own checkout, so several run at once.](https://shuriken.sh/guides/codex-worktrees-parallel-agents) - [Git worktrees eat disk space: how to keep it under control: Guide 27 Oct 2026 5 min read Each git worktree uses disk space: a full checkout plus its own dependencies and builds. How to measure it, prune old worktrees and share the heavy parts.](https://shuriken.sh/guides/git-worktree-disk-space) - [Resolving merge conflicts with Claude Code: Guide 27 Oct 2026 6 min read Parallel Claude Code agents still hit merge conflicts. Merge one branch, rebase the next onto it, give Claude both intents and test before you continue.](https://shuriken.sh/guides/resolve-merge-conflicts-with-claude-code) ## Free tools - [Claude limit reset tracker](https://shuriken.sh/tools/limit-resets/claude) - [Codex limit reset tracker](https://shuriken.sh/tools/limit-resets/codex)