[DOCS] `--add-dir` can load CLAUDE.md from additional directories (new in 2.1.20, undocumented)

Status Fixed / completed

Reported on v2.1.20

Maintainer reply None cached

Activity 3 comments · opened Jan 27, 2026 · closed Feb 8, 2026

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/memory

Section/Topic

"How Claude looks up memories" section, and related documentation in cli-reference.md, iam.md, and settings.md

Current Documentation

The memory.md page documents CLAUDE.md loading behavior:

Claude Code reads memories recursively: starting in the cwd, Claude Code recurses up to (but not including) the root directory / and reads any CLAUDE.md or CLAUDE.local.md files it finds.

The cli-reference.md documents --add-dir:

Add additional working directories for Claude to access (validates each path exists as a directory)

The iam.md documents working directories:

During startup: Use --add-dir <path> CLI argument 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.

None of these mention the new ability to load CLAUDE.md files from additional directories.

What's Wrong or Missing?

Claude Code 2.1.20 added a new feature:

Added support for loading CLAUDE.md files from additional directories specified via --add-dir flag (requires setting CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1)

This feature allows users to load CLAUDE.md memory files from directories specified via --add-dir, not just the current working directory and its parent chain. However:

A. Missing environment variable documentation

The environment variable CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD is not documented anywhere.

B. Missing behavior documentation

The memory.md page does not explain that additional directories can serve as memory sources when this environment variable is enabled.

C. Missing cross-references

The cli-reference.md and iam.md pages documenting --add-dir do not mention this memory-loading capability.

Suggested Improvement

In memory.md ("How Claude looks up memories" section)

Add after the existing paragraph about recursive memory loading:

Additional directory memories

When you add directories with --add-dir, /add-dir, or additionalDirectories in settings, Claude can optionally load CLAUDE.md files from those directories as well.

To enable this feature, set the environment variable:

export CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1

With this enabled, any CLAUDE.md or CLAUDE.local.md files found in additional directories are loaded alongside your project memories.

<Note>
This feature is opt-in to maintain backward compatibility. Without the environment variable, additional directories only extend file access—they don't contribute to memory.
</Note>

In cli-reference.md (--add-dir row)

Update the description to:

Add additional working directories for Claude to access. When CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 is set, also loads CLAUDE.md files from these directories. See memory documentation.

In iam.md ("Working directories" section)

Add after the existing bullet points:

<Tip>
Set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 to also load CLAUDE.md memory files from additional directories. See memory documentation for details.
</Tip>

In settings.md (environment variables section if exists, or add one)

Document the environment variable:

| Variable | Description |
|----------|-------------|
| CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD | When set to 1, loads CLAUDE.md files from additional directories specified via --add-dir, /add-dir, or additionalDirectories setting |

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:
| Page | Issue |
|------|-------|
| https://code.claude.com/docs/en/memory | Missing section on additional directory memory loading |
| https://code.claude.com/docs/en/cli-reference | --add-dir description incomplete |
| https://code.claude.com/docs/en/iam | Working directories section missing memory loading tip |
| https://code.claude.com/docs/en/settings | Environment variable not documented |

Total scope: 4 pages affected

Version introduced: Claude Code 2.1.20

View original on GitHub ↗

3 Comments

nielskaspers · 8 months ago

Checked the current docs—good news: memory.md already has the documentation in the "Load memory from additional directories" section! 🎉

However, the cli-reference.md --add-dir row could benefit from a cross-reference:

Current cli-reference.md

| Flag | Description |
|------|-------------|
| --add-dir | Add additional working directories for Claude to access (validates each path exists as a directory) |

Suggested update

| Flag | Description |
|------|-------------|
| --add-dir | Add additional working directories for Claude to access. Set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 to also load CLAUDE.md files from these directories. See [memory docs](/en/memory#load-memory-from-additional-directories). |

---

This way users discovering --add-dir via cli-reference will know about the memory loading capability without needing to stumble upon it in memory.md.

coygeek · 8 months ago

Issue #21138 Verification

Title: [DOCS] --add-dir can load CLAUDE.md from additional directories (new in 2.1.20, undocumented)
Issue Date: 2026-01-27
Verification Date: 2026-02-07
Status: RESOLVED

---

Issue Summary

This issue reports that Claude Code 2.1.20 added support for loading CLAUDE.md files from directories specified via --add-dir (requiring CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1), but this feature was undocumented across memory.md, cli-reference.md, iam.md (now permissions.md), and settings.md.

---

Verification Results

Claim A: Missing environment variable documentation

Status: RESOLVED

Evidence:

docs/code.claude.com/docs/en/memory.md lines 129-132: Full documentation of CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD with usage example
docs/code.claude.com/docs/en/settings.md line 763: Environment variables table row: "Set to 1 to load CLAUDE.md files from directories specified with --add-dir. By default, additional directories do not load memory files"
docs/code.claude.com/docs/en/skills.md line 115: "CLAUDE.md files from --add-dir directories are not loaded by default. To load them, set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1."

Verdict: The environment variable is now documented in three locations: memory.md, settings.md, and skills.md.

---

Claim B: Missing behavior documentation in memory.md

Status: RESOLVED

Evidence in docs/code.claude.com/docs/en/memory.md:

Lines 125-133: "Load memory from additional directories" subsection explains:
--add-dir gives access to additional directories
By default, CLAUDE.md files are not loaded from these directories
Setting CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 enables memory loading
Which files are loaded: "CLAUDE.md, .claude/CLAUDE.md, and .claude/rules/*.md"

Verdict: The memory page now has a dedicated subsection covering this behavior.

---

Claim C: Missing cross-references in cli-reference.md and iam.md (now permissions.md)

Status: PARTIALLY RESOLVED

Evidence:

docs/code.claude.com/docs/en/cli-reference.md line 29: --add-dir row still says only "Add additional working directories for Claude to access (validates each path exists as a directory)" without mentioning CLAUDE.md loading or skill auto-discovery
docs/code.claude.com/docs/en/permissions.md lines 195-199: --add-dir mentioned in working directories context but doesn't reference memory loading capability

However, the primary discovery pages (memory.md and skills.md) now both document this clearly, and the settings.md env vars table includes it. The cli-reference and permissions pages lack explicit cross-references but users searching for --add-dir behavior would find it via the memory and skills pages.

Verdict: The primary documentation gaps are filled. Cross-page mentions in cli-reference and permissions are a minor polish item.

---

Current State

| Claim | Status |
|-------|--------|
| CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD env var documented | RESOLVED |
| Behavior documented in memory.md | RESOLVED |
| Cross-references in cli-reference.md and permissions.md | PARTIALLY RESOLVED |

---

Suggested Fix

N/A for core issue. Optional enhancement: add a brief note to cli-reference.md --add-dir row mentioning memory loading with the env var.

---

References

URL: https://code.claude.com/docs/en/memory#load-memory-from-additional-directories
Lines 125-133 in mirror: "Load memory from additional directories" section

URL: https://code.claude.com/docs/en/settings
Line 763 in mirror: CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD in env vars table

URL: https://code.claude.com/docs/en/skills#skills-from-additional-directories
Lines 110-116 in mirror: Skills from additional directories section with env var cross-reference

URL: https://code.claude.com/docs/en/cli-reference
Line 29 in mirror: --add-dir row (still lacks cross-reference)

---

Conclusion & Recommendation

Primary Concern: Users could not discover that --add-dir directories can serve as memory sources, and the required environment variable was undocumented.

Resolution Status: RESOLVED

Recommendation: CLOSE

The core issue (undocumented env var and behavior) is fully resolved across memory.md, settings.md, and skills.md. The remaining cross-page gap in cli-reference.md is a minor polish item that doesn't prevent feature discovery.

github-actions[bot] · 8 months ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.