Working across multiple directories & monorepos with --add-dir

Extend your workspace without changing directory — tested on a real monorepo layout.

One project folder isn't always enough

In a monorepo split across `apps/web` and `packages/ui`, opening just one folder means you can't check the other. `--add-dir` grants access to extra folders without changing your working directory.

Verified live on a scratch monorepo

With `apps/web` as the cwd and `packages/ui` added via `--add-dir`, a tightly-scoped prompt returned real file listings from both directories:

$ cd apps/web
$ claude --add-dir ../../packages/ui -p "run pwd, then ls ./, then ls ../../packages/ui" \
  --allowedTools "Bash(pwd)" "Bash(ls ./)" "Bash(ls ../../packages/ui)"

pwd → apps/web
ls ./ → index.tsx
ls ../../packages/ui → Button.tsx

Added directories don't auto-load their CLAUDE.md

Per the official docs (fetched 2026-07-29), a directory added this way does not load its own CLAUDE.md/.claude/rules by default — set `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` if you need that.

Write access extends there too

`--add-dir` isn't read-only — edits can land in the added folder. Use `permissions.deny` to protect shared packages from unintended changes.

Adding directories mid-session: /add-dir

Beyond the startup flag, `/add-dir /path/to/dir` works inside an interactive session, and can be repeated for multiple directories.

vs settings.json's additionalDirectories

That's a persistent setting; `--add-dir` is per-session. Use the settings.json version for combos you always need, `--add-dir` for one-off ones.

FAQ

What does --add-dir do?

Verified live: grants read/write access to an extra folder without changing your working directory.

Can I pass it multiple times?

Yes — repeat --add-dir A --add-dir B.

Does the added folder's CLAUDE.md load automatically?

No by default; set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD to load it too.

Can I add directories mid-session?

Yes, via /add-dir <path>.

Is this the same as settings.json's additionalDirectories?

Similar goal, different mechanism — that one is persistent, --add-dir is per-session.

Find configs for monorepos →See starter packs →See School →