How Claude Code works across multiple repos
Claude Code works across multiple repos by adding extra working directories to a session. Every session has one primary folder, the project you opened. You can add more with the /add-dir command, the --add-dir flag at launch, or the permissions.additionalDirectories setting. Once a folder is added, Claude can read and edit files in it alongside the main project, so one conversation can change a shared library and the app that uses it.
This comes up the moment real work spans two codebases: a frontend and a separate API, a website and the shared component kit it pulls from, or a client app plus the internal tool that feeds it. Without an added directory, Claude stays inside the folder you opened and asks before reaching outside it. With one, the cross-project change happens in a single pass instead of two sessions copying notes to each other.
Option 1: /add-dir for one session
- Open the project you will spend most of the time in. That becomes the primary folder, and its CLAUDE.md, settings and hooks are the ones that apply.
- In the prompt box, type /add-dir followed by the path to the second project, for example /add-dir ../api. Start typing a partial path and Claude Code suggests matching folders.
- Confirm the folder when asked. From then on Claude can read and edit files there for the rest of the session.
- Tell Claude what lives where in your first message: which folder is the app, which is the API, and which one the change starts in. It does not guess the relationship between two folders on its own.
If you start sessions from the terminal, the same thing at launch is claude --add-dir ../api, and you can pass more than one path. Added directories are remembered with the session too: resuming from the added folder still finds a session that added it with /add-dir.
Option 2: make the extra folder permanent in settings
If you add the same folder every day, stop typing it. Add the path to permissions.additionalDirectories in a settings file, and every new session in that project gets file access to it automatically. The desktop app reads the same settings files as the terminal, so this works in both. Claude Code settings.json explained covers where those files live and which one to use.
Put it in the project's local settings file if the path only makes sense on your machine, and in the shared project file only if every teammate keeps the repos in the same place. One catch: folders listed in this setting get file access only. Unlike /add-dir, they do not load the added folder's skills, commands or subagents.
What an added folder loads, and what it does not
This is where most cross-repo confusion comes from. Adding a directory widens where Claude can read and write. It does not turn that folder into a second project with its own full setup.
What Claude Code picks up from a folder added with /add-dir or --add-dir
| From the added folder | Loaded? |
|---|---|
| Skills in .claude/skills/ | Yes, and edits to them are picked up live |
| Commands in .claude/commands/ | Yes. If both projects define the same command name, the main project's wins |
| Subagents in .claude/agents/ | Yes |
| CLAUDE.md and .claude/rules/ | Only if the CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD environment variable is set to 1 |
| Settings in .claude/settings.json | Only the plugin keys (enabledPlugins and extraKnownMarketplaces). Permissions, hooks and the rest stay with the main project |
My recommendation: keep the instructions that matter for the joint work in the main project's CLAUDE.md, including a short line on what the second repo is and its rules. That way the context loads every time without an environment variable, and it is obvious which project is in charge. The Claude Code CLAUDE.md file covers what to write.
Multiple repos in the desktop app's cloud sessions
Cloud sessions in the desktop app support several repositories directly. After you pick a cloud environment, click the + button next to the selected repository to add more. Each repository gets its own branch selector, so you can work on a feature branch in the library and a matching branch in the app that consumes it. This is the desktop equivalent of --add-dir for work that runs in the cloud rather than on your machine.
Cloud sessions suit long, cross-repo jobs you want running while you do something else, such as updating a shared package and every project that depends on it. Claude Code on the web covers how cloud sessions work, and the Claude Code desktop app covers the rest of the app.
When to open a parent folder or move the session instead
- Open the parent folder when both repos sit side by side and you want each one's CLAUDE.md to count. Claude loads a subfolder's CLAUDE.md when it reads or edits a file in that subfolder, so each repo's rules apply when Claude works there. The tradeoff: settings, hooks and the dev server preview come from the parent folder you opened, not from each repo.
- Use /cd when the work is finished in one repo and continues in another. It moves the session to the new folder and keeps the conversation, then applies that folder's CLAUDE.md, settings and hooks, asking you to trust the folder first if it is new.
- Use two separate sessions when the projects belong to different clients. Keeping client code, keys and history apart matters more than saving a few minutes. Claude Code worktrees covers the related case of two sessions in the same repo.
A simple cross-repo routine
- Open the project where the change starts. Add the other with /add-dir.
- Say in plain words which folder is which and what has to change in each.
- Ask for a plan first and check that it names files in both folders. Claude Code plan mode is built for this.
- Let Claude make the change, then run each project and its tests separately.
- Commit in each repo on its own, with a message that mentions the other, so the two changes can be traced together later. Use Claude Code with Git covers the commit habit.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
Can Claude Code work on multiple repos at once?
Yes. Open one project, then add the other with /add-dir and its path, or start with the --add-dir flag. Claude can read and edit files in both folders for the rest of the session.
How do I permanently add a directory in Claude Code?
Add the folder path to permissions.additionalDirectories in a settings file. New sessions in that project get file access to it automatically. It grants file access only and does not load the folder's skills, commands or subagents.
Does Claude Code read the CLAUDE.md in an added directory?
Not by default. A folder added with --add-dir or /add-dir only loads its CLAUDE.md and rules when the CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD environment variable is set to 1. The simpler route is to describe the second repo in the main project's CLAUDE.md.
How do I add multiple repositories in the Claude Code desktop app?
In a cloud session, pick a cloud environment and click the + button next to the selected repository to add more. Each repository gets its own branch selector. For local sessions, use /add-dir or the additionalDirectories setting, which the desktop app reads from the same settings files as the terminal.
What is the difference between /add-dir and /cd in Claude Code?
/add-dir keeps your current project as the main one and adds file access to another folder. /cd moves the whole session to a new folder, keeps the conversation, and applies that folder's CLAUDE.md, settings and hooks.
Last reviewed by David Iya on October 7, 2026
