Working directories

By default, Claude has access to files in the directory where you launched it. That directory is the session's primary working directory until you move the session with /cd. You can extend this access:

• During startup: use --add-dir <path> CLI argument
• During session: use /add-dir command
• Persistent configuration: add to additionalDirectories in settings files

Files in additional directories follow the same permission rules as the original working directory: they become readable without prompts, and file editing permissions follow the current permission mode.

You can't add most network paths, such as the UNC share \\server\share, as working directories, because looking one up can contact the host it names. On Windows, map the share to a drive letter instead and pass the drive with --add-dir at launch.

Set permissions.blockReadsOutsideWorkingDirectories to make the file tools refuse the paths it fences in every permission mode. In auto mode, Claude Code offers to turn it on the first time Claude reads outside the working directories.

In background sessions on macOS, the session host requests access to protected folders such as ~/Desktop, ~/Documents, and ~/Downloads separately from your terminal when Claude needs to read or write files there; if reads there fail with Operation not permitted, see how to grant folder access to background sessions.

Move the session to another directory

To move the session to a different primary working directory, rather than adding a directory alongside the current one, run /cd <path>. Claude Code keeps the conversation, loads the new directory's CLAUDE.md, and prompts you to trust the workspace if you haven't worked in it before. Afterward, Claude Code finds the moved session when you run --resume from the new directory.

As soon as you move, Claude Code applies the new directory's project configuration:

• Its project settings, including their permission rules and hooks
• Its .mcp.json servers, subject to the same server approval as at startup, and the local-scope MCP servers you registered in it
• The plugins its settings enable, its skills, and its subagents
• Its env values, applied on top of the environment variables from the previous directory's settings, which stay in effect

Claude Code also disconnects the previous directory's project and local-scope MCP servers, and the servers of plugins that are no longer enabled after the move. It takes additional directories from the new directory's settings instead of the previous one's, and keeps the directories you added with --add-dir or /add-dir. Hooks the move activates still receive $\{CLAUDE_PROJECT_DIR\} set to the project root where the session started.

When the new directory isn't trusted yet, Claude Code lists in the trust prompt the allow rules, additional directories, hooks, and helper commands the directory's settings would activate, so you can review them before you accept. If you decline, the session stays where it is. Before v2.1.246, /cd didn't apply the new directory's settings, hooks, MCP servers, or skills until you resumed the session, and its trust prompt didn't list what the directory's settings would activate.

Restrict or disable /cd targets with Cd permission rules.

Additional directories grant file access, not configuration

Adding a directory extends where Claude can read and edit files. It doesn't make that directory a full configuration root: most .claude/ configuration is not discovered from additional directories, though a few types are loaded as exceptions.

These exceptions apply only to directories added with the --add-dir flag or the /add-dir command, including directories the Agent SDK adds through the flag. Directories listed in permissions.additionalDirectories in a settings file grant file access only and don't load any of the configuration below.

The Agent SDK's additionalDirectories option in TypeScript and add_dirs option in Python receive the exceptions too, even though the TypeScript option shares its name with the settings key. The SDK passes each entry to Claude Code as --add-dir, so those directories behave like flag-added directories. Skills, commands, and subagents from any flag-added directory load through the project setting source, so they don't load when you exclude that source with --setting-sources on the CLI or settingSources in the SDK, and bare mode skips the commands and subagents among them.

The following configuration types are loaded from --add-dir directories:

Configuration	Loaded from --add-dir
Skills in .claude/skills/	Yes, with live reload
Command files in .claude/commands/	Yes, without live reload. When the added directory and your project both define a command with the same name, Claude Code runs your project's command
Subagents in .claude/agents/	Yes, without live reload
Settings in .claude/settings.json and .claude/settings.local.json	enabledPlugins and extraKnownMarketplaces keys only
CLAUDE.md files, .claude/rules/, and CLAUDE.local.md	Only when CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 is set. CLAUDE.local.md additionally requires the local setting source, which is enabled by default

To load the skills, commands, and subagents from a subdirectory of your primary working directory mid-session, run /add-dir with that subdirectory's path. Claude Code loads them for the rest of the session without prompting you or adding a working directory, because the subdirectory is already readable. This requires Claude Code v2.1.257 or later.

Claude Code discovers output styles from the current working directory and its parents, your user directory at ~/.claude/, and managed settings. Hooks and other .claude/settings.json keys load from the current working directory's .claude/ folder with no parent-directory fallback, alongside your user ~/.claude/settings.json and managed settings. .claude/settings.local.json loads from the git repository root instead, even when you start Claude Code in a subdirectory, except in the cases where Claude Code doesn't use the repository root, such as on Windows; before v2.1.211, it too loaded only from the current working directory. Agent SDK sessions load it from the working directory in all versions.

To share that configuration across projects, use one of these approaches:

• User-level configuration: place files in ~/.claude/agents/, ~/.claude/output-styles/, or ~/.claude/settings.json to make them available in every project
• Plugins: package and distribute configuration as a plugin that teams can install
• Launch from the config directory: run Claude Code from the directory containing the .claude/ configuration you want