Multi-Directory and Monorepo Setup in Claude Code

## Overview

A Claude Code session can read and edit files in its working directory by default. Working across more than one directory comes up in two common situations:

- **A monorepo**, where a change to a shared package needs matching edits in the packages that import it.
- **Separate repositories** checked out side by side, where one task spans both.

Claude Code gives you three ways to grant access beyond the working directory: the `--add-dir` launch flag, the `/add-dir` in-session command, and the `permissions.additionalDirectories` setting. They differ mainly in scope (one session versus committed config) and in what they load from the added directory: file access only, or also that directory's `CLAUDE.md`, rules, and skills.

This guide covers those three mechanisms and the decision that comes before them: where to start Claude.

## Choose where to start Claude

Before adding directories, pick your launch point. Where you run `claude` determines which files Claude can touch without a grant and which `CLAUDE.md` files load at startup.

| Start from      | File access                            | CLAUDE.md loaded at launch                              | Use when                                   |
| :-------------- | :------------------------------------- | :----------------------------------------------------- | :----------------------------------------- |
| Repository root | Every file in the tree                 | Root only; subdirectory files load on demand           | Tasks span multiple packages or subsystems |
| A subdirectory  | That subtree only, until you grant more | That directory's plus every ancestor's                 | Work is scoped to one package or subsystem |

If you start from the repository root of a single large tree, Claude already reaches every file and you do not need to add directories. The mechanisms below matter when you start from a subdirectory, or when a task spans separate checkouts.

Note that project settings in `.claude/settings.json` load only from the directory you start in; they are not inherited from parent directories the way `CLAUDE.md` files are.

## Grant access for one session: `--add-dir` and `/add-dir`

To add a directory at launch, pass `--add-dir`:

```bash
# Start in packages/api and also reach the sibling shared package
claude --add-dir ../shared

# Multiple directories, including a separate repository
claude --add-dir ../shared --add-dir ~/code/other-repo
```

To add a directory after a session has already started, use the `/add-dir` command:

```text
/add-dir ../web
```

Either way, Claude can read and edit files in the added directory for the rest of that session. Neither change is persisted; the next session starts from your working directory again.

By default, a directory added this way does **not** load its `CLAUDE.md`, `.claude/rules/`, or `CLAUDE.local.md`. To also load those memory files, set the `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` environment variable:

```bash
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config
```

With the variable set, Claude loads `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md`, and `CLAUDE.local.md` from the added directory. (`CLAUDE.local.md` is skipped if you exclude `local` from `--setting-sources`.) Skills in an added directory load on demand regardless of this variable.

## Grant access permanently: `additionalDirectories`

To make sibling access part of the project so everyone working in this area gets it, use the `permissions.additionalDirectories` setting in `.claude/settings.json`:

```json
{
  "permissions": {
    "additionalDirectories": [
      "../shared",
      "../web"
    ]
  }
}
```

Relative paths resolve against the directory you start Claude from. With the configuration above, a session launched in `packages/api/` can read and edit files in `packages/shared/` and `packages/web/` without any flag.

Commit the setting to `.claude/settings.json` for everyone, or put it in `.claude/settings.local.json` for a personal, gitignored selection.

Unlike `--add-dir`, the `additionalDirectories` setting grants **file access only**. It never loads the added directory's `CLAUDE.md`, rules, or skills, and the `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` variable has no effect on it. If you need a sibling's instructions or skills loaded, add it with `--add-dir` instead.

## Reference: which mechanism loads what

| Added with                             | Scope               | Read/edit access | Loads CLAUDE.md and rules                  | Loads skills |
| :------------------------------------- | :------------------ | :--------------- | :----------------------------------------- | :----------- |
| `additionalDirectories` setting        | Committed / local config | Yes         | Never                                      | Never        |
| `--add-dir` flag                       | One session         | Yes              | Only with `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` | Yes          |
| `/add-dir` command                     | Rest of the session | Yes              | Only with `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` | Yes          |

Pick based on intent: `additionalDirectories` for stable, team-wide sibling access where you only need files; `--add-dir` / `/add-dir` for one-off access, or when you want the sibling's conventions and skills in context too.

## Monorepo layout that scales

Adding directories is one of several settings that keep Claude focused in a large codebase. A typical monorepo combines them:

- **Layer `CLAUDE.md` files by directory.** A root file sets repository-wide rules; each package adds its own. Claude loads the root plus the package you start in, and pulls in a subdirectory's file on demand when it reads there. Keep each file focused on its own area so context is not spent on unrelated subsystems.
- **Exclude irrelevant `CLAUDE.md` files** with `claudeMdExcludes` (glob patterns matched against absolute paths) for packages you never touch, such as other teams' code or vendored subtrees.
- **Block reads of generated and vendored code** with `Read` deny rules in `permissions.deny`, for example `"Read(./**/dist/**)"` and `"Read(./vendor/**)"`. Searches already respect `.gitignore`, so this is for checked-in artifacts.
- **Grant sibling access** with `additionalDirectories` when a change spans packages.

A committed `packages/api/.claude/settings.json` that combines these:

```json
{
  "permissions": {
    "additionalDirectories": [
      "../shared"
    ],
    "deny": [
      "Read(./**/dist/**)",
      "Read(./**/build/**)"
    ]
  }
}
```

Because project settings load only from your starting directory, each subdirectory's `.claude/settings.json` must be self-contained rather than layered on a root file.

## Worktrees and sparse paths

If you start sessions in a new git worktree with `--worktree`, the entire repository is checked out by default. In a large repository, the `worktree.sparsePaths` setting uses git sparse-checkout to write only the listed directories (plus root-level files) to disk:

```json
{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  }
}
```

Paths are relative to the repository root regardless of where you launch Claude. List directories, not individual files; root-level files like lock files and `tsconfig.base.json` are always included. Add `.claude` if you want the repository root's `.claude/` available inside the worktree. Pair with `symlinkDirectories` to avoid duplicating large directories such as `node_modules` across worktrees.

Note that `sparsePaths` and `symlinkDirectories` are read from your starting directory before the worktree is created; after creation the session's working directory is the worktree root, so put permission rules and hooks you need inside worktrees in the repository root's `.claude/settings.json`.

## Scoping a change that spans packages

Configuration controls what Claude can see; how you scope the task affects the result:

- **Hand over the whole change in one session.** Giving Claude the shared edit and its call sites together keeps decisions consistent across packages instead of being re-derived per package.
- **Save the plan to a file before editing.** A long cross-package session compacts its context along the way; a plan written to a markdown file in the repository survives where conversation history may not.

## Troubleshooting

- **Claude says it cannot edit a sibling package.** You started in a subdirectory without granting the sibling. Add it with `--add-dir`, `/add-dir`, or `additionalDirectories`, or start Claude from the repository root.
- **A sibling's `CLAUDE.md` is being ignored.** The `additionalDirectories` setting never loads memory files. Use `--add-dir` with `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`, or layer a `CLAUDE.md` in your own tree instead.
- **A relative path resolves to the wrong place.** Relative paths resolve against the directory you start Claude in, not the repository root (sparse paths are the exception). Confirm your launch directory, or use an absolute path.
- **Settings in `.claude/settings.json` are not taking effect.** Project settings load only from the directory you start in. A root settings file does not apply when you launch from a subdirectory.

## Related resources

- [Set up Claude Code in a monorepo or large codebase](https://code.claude.com/docs/en/large-codebases)
- [Settings reference](https://code.claude.com/docs/en/settings)
- [Memory and project instructions](https://code.claude.com/docs/en/memory)