Quick answer (checked 12 October 2026): Start Claude Code in your main repository and give it access to sibling repos with
claude --add-dir ../other-repo(or/add-dirduring a session). Put project rules inCLAUDE.md. Note that CLAUDE.md files in added directories are not loaded by default; setCLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1if you want them. For safety, turn on Claude Code's built-in sandbox (/sandbox), which limits where Bash commands can write and which domains they can reach. For CI, run it headless withclaude -p "...".
Real features rarely live in one repository: an API change touches the backend service, the web client and a shared types package. Claude Code can work across all of them in one session, but only if you set it up properly. This guide sticks to features that exist in Claude Code's official documentation and its CLI help. Many guides online invent config files and flags, so I've checked each one.
Step 1: Give Claude access to more than one repository
By default Claude Code works inside the directory you start it in. To add sibling repositories:
# Start in the service you are changing, and allow two related repos
cd ~/code/billing-service
claude --add-dir ../web-frontend ../shared-types
Or, in an existing session, type:
/add-dir ../web-frontend
For directories you always want available, there is also a permissions.additionalDirectories setting in your Claude Code settings file.
There is no special "workspace" file or folder of symbolic links required. --add-dir is the supported way to do this.
Step 2: Put the rules in CLAUDE.md
CLAUDE.md is Claude Code's project memory: instructions it reads at the start of every session. According to the memory docs:
- Claude Code loads
CLAUDE.md(andCLAUDE.local.md) from the current directory and every directory above it when it starts. Files in subdirectories load when Claude works in them. - Common locations:
./CLAUDE.mdor./.claude/CLAUDE.mdfor the project (commit it so the team shares it),~/.claude/CLAUDE.mdfor your personal rules, and./CLAUDE.local.mdfor personal project notes you don't commit. - Run
/contextto see which memory files are loaded.
The multi-repo catch: CLAUDE.md files inside directories you add with --add-dir are not loaded by default. If each repo has important rules, enable them explicitly:
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../web-frontend ../shared-types
Directories added through the additionalDirectories setting never load their CLAUDE.md, even with this variable.
A short example CLAUDE.md for a billing service:
# Billing service
- Never edit files in migrations/ without asking first.
- Changes to the invoice API must stay backward compatible with web-frontend.
- Run `npm test` before saying a task is done.
- Shared request/response types live in ../shared-types; update them there, not locally.
Step 3: Turn on the sandbox
Letting an agent run shell commands on your machine is powerful and risky. Claude Code's built-in sandboxed Bash tool adds two layers of isolation (sandboxing docs):
- Filesystem isolation: sandboxed commands can write only to the working directory, a per-user temp directory and any directories you added (with
--add-dir,/add-diroradditionalDirectories). They can still read the rest of the filesystem, including credential files, so the docs recommend addingdenyReadrules for sensitive locations like your home-directory credentials. - Network isolation: network access goes through a proxy with an allowlist that starts empty, so you decide which domains (your package registry, for example) commands can reach.
Enable it with the /sandbox command. A few details from the docs:
- It covers Bash, PowerShell and Monitor commands and their child processes. Claude's built-in file tools, MCP servers and hooks still run on the host unless you isolate the whole process.
- On Linux and WSL2, it needs
bubblewrapandsocatinstalled. - For stronger isolation, run the entire Claude Code process inside isolation, for example with Anthropic's sandbox runtime (
npx @anthropic-ai/sandbox-runtime claude) or a dev container. - If you ever use
--dangerously-skip-permissions, the docs say to run it only inside a container, VM or the sandbox runtime.
Step 4: Pick a permission mode
Claude Code asks before editing files or running commands unless you tell it otherwise. The --permission-mode flag accepts modes including manual, acceptEdits, auto and bypassPermissions, and you can pre-approve specific tools with --allowedTools. A sensible setup for multi-repo work:
acceptEditsinside the sandbox, so Claude can edit files across the added repos without asking each time, while risky commands still need your approval.- Keep
manualfor repositories with production configuration or infrastructure code.
See the permissions docs for allow and deny rules.
Step 5: Run it headless in CI
For automation, use print mode, which answers and exits (headless docs):
claude -p "Run the test suite, find the cause of the failing invoice test, and propose a minimal fix" \
--output-format json
For GitHub workflows, Anthropic maintains the Claude Code GitHub Action, which can respond to comments on issues and pull requests.
A practical multi-repo checklist
- Start in the repo you are changing;
--add-dirthe others. - Commit a
CLAUDE.mdin each repo with its rules, and setCLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1if you need them all. - Turn on
/sandboxand adddenyReadrules for credentials. - Allow only the network domains you need.
- Review every diff before committing. Claude Code doesn't replace code review.
Frequently asked questions
How do I use Claude Code with multiple repositories?
Start it in one repository and add the others with claude --add-dir ../repo-a ../repo-b, or /add-dir during a session.
Does Claude Code read CLAUDE.md from added directories?
Not by default. Set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 when launching to load them.
Can Claude Code run in CI?
Yes. Use claude -p "your task" for non-interactive runs, optionally with --output-format json, or the official GitHub Action.
Does the sandbox stop Claude from reading my secrets?
Not on its own. By default sandboxed commands can still read most of the filesystem; add denyRead rules for credential locations.
Sources
- Claude Code Docs: CLI reference
- Claude Code Docs: How Claude remembers your project (CLAUDE.md)
- Claude Code Docs: Configure the sandboxed Bash tool
- Claude Code Docs: Configure permissions
- Claude Code Docs: Run Claude Code programmatically
- Claude Code Docs: Set up Claude Code in a monorepo or large codebase
- GitHub: anthropics/claude-code-action
Related on VNHAX: Claude Code vs Antigravity vs Grok Build · Multi-persona agent swarms with Everything Claude Code · Hardening enterprise MCP servers
