AI Coding Guide

Why the CLAUDE.md in a --add-dir directory is not loaded, and the setting that fixes it

Claude Code Published:

A --add-dir directory does not load its CLAUDE.md by default. What CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD changes, which files it covers, and how to make it permanent.

Verified on Sep 10, 2026 These tools change quickly. Please also check the latest official documentation.
#Claude Code#CLAUDE.md#--add-dir#additionalDirectories#environment variables
Contents
  1. --add-dir does not discover configuration
  2. Loading it with CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD
  3. Making it permanent
  4. Summary

Keeping shared conventions in a separate repository and pointing Claude Code at it with claude --add-dir ../shared-config is a common setup. It is also a common source of confusion, because the instructions in shared-config/CLAUDE.md seem to be ignored.

In short: the CLAUDE.md in a directory added with --add-dir is not loaded by default. It loads only when the CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD environment variable is set.

KEY POINT

What you will learn

  • That --add-dir grants file access, not configuration discovery
  • Which files CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD loads
  • How this relates to permissions.additionalDirectories, and how to make it permanent

--add-dir does not discover configuration

--add-dir (or /add-dir inside a session) treats a location outside the launch directory as an additional working directory so Claude can read and write files there. The official docs state that most .claude/ configuration is not discovered from these directories. CLAUDE.md falls under that rule and is skipped by default.

The settings-file equivalent is permissions.additionalDirectories. It plays the same role: it grants file access, and it does not load the directory's CLAUDE.md.

{
  "permissions": {
    "additionalDirectories": ["../shared-config/"]
  }
}

用語解説

Working directories: the directories that define where Claude Code is allowed to read and write. The launch directory is one, and --add-dir, /add-dir, and permissions.additionalDirectories add more.

Loading it with CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD

To also load memory files from additional directories, set the variable when launching:

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

These files at the top of each additional directory are then loaded:

FileLoaded
CLAUDE.mdyes
.claude/CLAUDE.mdyes
.claude/rules/*.mdyes
CLAUDE.local.mdyes, unless local is excluded via --setting-sources

The environment variables page describes the variable as a colon-separated list of additional directories (semicolon-separated on Windows) where Claude Code looks for CLAUDE.md files, while the memory page's example sets it to 1 alongside --add-dir. Whether both forms behave identically could not be confirmed from the official documentation. Start with the documented =1 plus --add-dir form, and fall back to listing the directory paths as the value if it does not take effect.

Making it permanent

If you do not want to type the variable every time, put it under the env key in a settings file. Values there apply to every session and its subprocesses, and they override a variable of the same name set in your shell.

{
  "env": {
    "CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD": "1"
  },
  "permissions": {
    "additionalDirectories": ["../shared-config/"]
  }
}

With that in place, a plain claude gives you access to ../shared-config/ and loads its CLAUDE.md.

Only load CLAUDE.md from directories you control

A CLAUDE.md in an additional directory hands its author's instructions straight to Claude. If you --add-dir a repository you cloned from someone else and enable this variable, you are opening the door to instructions you did not write. Keep it to directories your own team maintains, such as a shared configuration repository.

To confirm the file loaded, run /context in the session and look for the additional directory's CLAUDE.md under Memory files. If the shared instructions are short, importing them from your own CLAUDE.md with @path syntax is simpler than the environment variable. The overall layering of CLAUDE.md files is covered in the hub article How to write CLAUDE.md, and subdirectory loading in When does Claude Code load a CLAUDE.md in a subdirectory?.

Summary

  • --add-dir and permissions.additionalDirectories grant file access only; the CLAUDE.md there is not loaded by default
  • Set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD to load CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md, and CLAUDE.local.md from those directories
  • Put the variable under env in settings.json to make it permanent
  • Do not enable it for directories you do not control
  • Verify under Memory files in /context

FAQ

Is the CLAUDE.md in a --add-dir directory loaded automatically?
No. By default memory files from additional directories are not loaded. Set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 to load them.
Does permissions.additionalDirectories load it?
It grants file access to the directory, but most .claude/ configuration there is not discovered. You still need the same environment variable to load its CLAUDE.md.
How do I avoid setting the variable every time?
Put it under the env key in settings.json; it then applies to every session.

Primary sources

This article was drafted by AI from official documentation and reviewed by the site operator before publishing. Found a mistake? Let us know via the contact page.

Related articles