Omniscio

OmniscioGuidesMultiple directories (--add-dir)

Claude Code multiple directories: how --add-dir works

A front end and a shared library rarely live in one folder, and moving the session is not what you want when you still need the first one open.

This page covers the three ways to add a folder, what an added folder does and does not change, the one environment variable that brings its CLAUDE.md along, and the difference between adding a folder and moving to it.

Last checked against Anthropic's Claude Code documentation on November 18, 2026. By the Omniscio team. Updated .

The three ways to add a folder

Anthropic documents the same idea three times, once per lifetime: one launch, one session, or every session from then on.

  • At startup. claude --add-dir ../apps ../lib adds several directories in one command. Claude Code checks that each path exists as a directory.
  • Mid-session. /add-dir <path> in a running session. Type a partial path and press Tab to accept a suggestion; after a successful add your DirectoryAdded hooks run.
  • Persistently. permissions.additionalDirectories in a settings file — .claude/settings.json for the team, ~/.claude/settings.json for you — written as { "permissions": { "additionalDirectories": ["../docs/"] } }.

The first two are the same mechanism: the SDK passes its own directory option to Claude Code as --add-dir, so a folder added from code behaves like one added from a flag. The settings key is the odd one out, and the next two sections are about why that matters.

Sources: the --add-dir row in the CLI reference, /add-dir in the commands reference, and permissions.additionalDirectories, read November 18, 2026.

What an added folder gives Claude

An added directory becomes a working directory, and files in it follow the same permission rules as the folder you started in. Anthropic's wording is that they become readable without prompts, apart from the network-path check, and that editing follows the current permission mode.

That last part is the one people misread. In a mode that asks before edits, Claude asks before edits in the added folder too. Adding a folder widens where Claude may work, not what it may do.

The block settings count added folders too. If permissions.blockReadsOutsideWorkingDirectories is on, a folder added with --add-dir, /add-dir or the user or managed settings key counts as inside the boundary. A folder listed only in a repository's .claude/settings.json does not count for that block.

Sources: "Working directories" and the linked block settings in Anthropic's permissions page, read November 18, 2026.

What does and does not load from it

This is the part that surprises people. An added folder is a place to read and edit files, not a second configuration root, and Anthropic says most .claude/ configuration is not discovered from it.

These are the exceptions, and only for folders added with the flag or the command — the settings key grants file access and nothing else:

  • Skills in .claude/skills/ load, with live reload.
  • Commands in .claude/commands/ load without live reload. If your project and the added folder both define one with the same name, your project's wins.
  • Subagents in .claude/agents/ load without live reload.
  • Settings contribute only the enabledPlugins and extraKnownMarketplaces keys.
  • CLAUDE.md, .claude/rules/ and CLAUDE.local.md load only when CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 is set.

So a shared library with its own thorough CLAUDE.md will contribute nothing to the session by default, and a skill you keep there will just work. That asymmetry is documented, not a bug, and setting that variable is the switch for the other half. The CLAUDE.md guide covers which files load in a normal session.

Source: "Additional directories grant file access, not configuration" in Anthropic's permissions page, read November 18, 2026.

Adding a folder versus moving to it

/cd <path> is the other command people reach for, and it does something different: it moves the session's primary working directory and keeps the conversation.

The difference is configuration. A move applies the new directory's project settings and permission rules, its hooks, its .mcp.json servers, its plugins, skills and subagents, and its env values. It also disconnects MCP servers that belonged to the directory you left.

Folders you added with --add-dir or /add-dir survive the move. Folders that came from the old directory's settings are replaced by the new directory's. If the new directory has not been trusted yet, Claude Code shows you what its settings would activate before you accept.

The short version: add when you need a second folder, move when you have changed projects.

Source: "Move the session to another directory" in Anthropic's permissions page, read November 18, 2026.

When to add, and when not to

Adding a folder is the right move for a repository you own that sits beside the one you opened: a shared design system, a deployment config, a sibling service you are changing in step.

It is the wrong move for a folder you only need to look at once. Anthropic gives a narrower route for that: ask Claude to read the file, and approve the prompt. The difference matters because a working directory stays in place for the rest of the session.

For a monorepo the page to read first is Claude Code in a monorepo, which covers nested CLAUDE.md files and per-package skills rather than a second working directory.

Limits

  • Network shares. You cannot add most network paths, such as \\server\share. On Windows, map the share to a drive letter and pass the drive: claude --add-dir Z:\.
  • The path must exist. The flag validates each entry as a directory, so a typo is an error rather than a future folder.
  • Repository settings need trust. Directories in a project's .claude/settings.json take effect only after you accept the workspace trust dialog for that folder.
  • Bare mode trims it. In a --bare run, skills from an added directory still load, but commands and subagents among them are skipped.

Common mistakes

  • Expecting the second project's CLAUDE.md to load. It does not, unless CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 is set.
  • Using the settings key and expecting skills to appear. additionalDirectories grants file access only; use the flag or /add-dir for the configuration exceptions.
  • Reaching for /add-dir when you meant /cd. A moved session takes its new project's settings with it; an added folder does not.
  • Adding a mapped network drive by its UNC path. Map it to a letter first, then add the letter.
  • Assuming a terminal command is confined the same way. Shell commands and sandboxed writes are governed by their own rules.

Where these answers come from

  • The three ways in, and the network-path limit: CLI reference, commands reference and Configure permissions, read November 18, 2026.
  • The configuration table and the CLAUDE.md variable: "Additional directories grant file access, not configuration" in the same permissions page, read the same day.
  • Adding versus moving: "Move the session to another directory" in the same page, read the same day.
  • The settings key and the trust rule: the settings reference, read the same day.

Common questions

Can I add more than one folder at once?

Yes. --add-dir takes several paths, and Anthropic's own example passes two: claude --add-dir ../apps ../lib.

Does /add-dir work while Claude is answering?

Yes. Anthropic says Claude's next tool call can reach the directory once you confirm the add.

Is this the same as the Agent SDK's directory option?

Effectively. The SDK passes its option to Claude Code as --add-dir, so those directories get the same configuration exceptions.

Why does an added folder's settings file do so little?

Only enabledPlugins and extraKnownMarketplaces are read from it. Everything else in that file is ignored for the session.