CONCEPT The working-directory boundary
By default Claude Code operates against the directory where you launched it. That folder and its subfolders form the working-directory boundary:
- Claude can write only inside the working directory and its subfolders. It cannot modify files in parent directories without explicit permission.
- Reading outside the boundary with Read/Grep/Glob is possible, but each such path triggers an approval prompt first.
- Read-only Bash commands (
ls,cat, …) can reach broader paths; you can tighten that with sandboxdenyReadrules (see 3.4).
CONCEPT Extending access: --add-dir, /add-dir, additionalDirectories
Three ways to grant Claude access to a directory beyond where it started:
| Method | When | Also loads config? |
|---|---|---|
--add-dir <path> | At startup (CLI flag) | Yes — skills, subagents, and a few settings keys |
/add-dir | During a session | Yes — same as the flag |
permissions.additionalDirectories | Persistent (settings file) | No — file access only |
Files in an added directory follow the same permission rules and mode as the original working directory: they become readable without prompts, and editing follows the current permission mode.
permissions.additionalDirectories grant file access only — they do not
load any .claude/ configuration. Only the --add-dir flag and /add-dir
command load skills (with live reload) and subagents from an added directory./add-dir adds a directory to the boundary. To relocate the
session's primary working directory instead, use /cd — that loads the new directory's
CLAUDE.md and makes --resume find the session from there..claude/settings.json
grants capability, so Claude Code applies it only after you accept the workspace trust dialog
for that folder. Deny and ask rules aren't gated this way, since they only restrict.DIAGRAM Resolving where a path may be read or written
or an additional dir?"} IN -->|"yes"| RW["🟢 Read free · edit per current mode"] IN -->|"no — read attempt"| RP["🟠 Prompt to read outside boundary"] IN -->|"no — write attempt"| WP["🟠 Prompt: parent-dir write
needs explicit permission"] RW --> DENY{"Matches a Read/Edit
deny rule?"} DENY -->|"yes"| BLOCK["🔴 Blocked (deny wins)"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class RW ok; class RP gate; class WP gate; class BLOCK bad;
CODE Adding directories two ways
# At startup — a monorepo package plus a shared lib. # --add-dir also loads skills/subagents from those dirs. claude --add-dir ../shared-lib --add-dir ../design-system # Persistent, file-access-only, in .claude/settings.json. # These do NOT load .claude/ config from the added dirs. { "permissions": { "additionalDirectories": [ "../shared-lib", "~/reference-repos/api-spec" ] } }
/add-dir ../shared-lib does the same as the flag — including
picking up that directory's skills with live reload.TRADE-OFFS --add-dir vs. additionalDirectories
✅ --add-dir / /add-dir
- Grants file access and loads skills + subagents from the dir
- Great for multi-repo work where the other repo has its own tooling
- Explicit, per-session — nothing persists silently
⚖️ additionalDirectories setting
- Persistent and shareable via version control
- File access only — no config load, so no surprise skills/agents
- Still gated by the workspace-trust dialog when it lives in project settings
EXAM TRAPS
additionalDirectories loads that repo's skills and agents." → It does
not — it grants file access only. Use --add-dir / /add-dir to load
.claude/skills/ and .claude/agents/ from an added directory./add-dir and /cd do the same thing." →
/add-dir extends the boundary with another directory; /cd relocates the primary
working directory (loads its CLAUDE.md, changes where --resume finds the session).PRACTICE
Q1 · You add a sibling repo with additionalDirectories but its skills don't appear. Why?
The additionalDirectories setting grants file access only and does not load
.claude/ config. Start with --add-dir ../that-repo (or run /add-dir) to
load its skills and subagents.
Q2 · Can Claude edit ../config/app.yml if you launched it in ./service?
Not without extra permission. ../config is a parent/sibling outside the working
directory, so writes there require an explicit approval or adding that directory to the boundary.
Q3 · A project's .claude/settings.json adds an allow rule and an additional directory, but neither applies. What's missing?
The workspace trust dialog. Allow rules and additional directories in project settings grant capability, so they apply only after you accept trust for that folder. Deny/ask rules apply regardless.