Work Across Your Whole Monorepo at Once: --add-dir and CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD

--add-dir extends Claude Code's workspace to any directory; set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 and each added directory's CLAUDE.md loads automatically — one flag unlocks full monorepo context with per-package rules.

Working in a monorepo or pulling context from a shared standards repo usually means either duplicating CLAUDE.md content everywhere or manually reading each file into the conversation. --add-dir fixes the first problem; a recently added environment variable fixes the second.

The basics: --add-dir

The flag gives Claude Code read and write access to directories outside the current working directory:

claude --add-dir ../../packages/shared-api --add-dir ../../packages/ui

You can also add directories during an active session:

/add-dir ../../packages/shared-api

Claude sees all files in the added directories, can edit them, and references them in generated code — treating them as first-class parts of the workspace.

The new part: per-directory CLAUDE.md inheritance

By default, --add-dir only extends file access. Set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 and Claude also loads that directory's CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md, and CLAUDE.local.md files:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 \
  claude --add-dir ../../packages/shared-api

Now packages/shared-api/CLAUDE.md — which might document the API's naming conventions, error patterns, and auth model — loads automatically alongside your project's own CLAUDE.md. Each package's rules apply exactly where they should.

Three patterns that use this

Shared standards repo. Keep a central ~/company-standards/ with conventions for error handling, logging, and security. Add it to every session via a shell alias:

alias cc='CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ~/company-standards'

Monorepo multi-package work. When editing apps/api that consumes packages/shared, add the shared package so Claude sees the actual source rather than inferring from types — catching interface mismatches before you propose them.

Cross-service API alignment. Adding the consuming service's directory when editing the provider lets Claude see how the API is actually used, surfacing breaking changes before they ship.

What loads vs. what doesn't

The env var is opt-in for backward compatibility. Without it, additional directories contribute files but not memory. With it, each added directory participates in the same CLAUDE.md hierarchy as your main project. Project-level settings (.claude/settings.json, hooks) remain tied to the original working directory — memory inheritance applies only to the .md rules files.

Sources: How Claude Remembers Your Project — Claude Code Docs · --add-dir Guide — ClaudeLog · CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD (GitHub issue #21138) · Multi-Directory Setup Guide — HeyClaude