[BUG] .claude/CLAUDE.local.md not auto-loaded at session start (root-level CLAUDE.local.md works)

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

.claude/CLAUDE.local.md is silently ignored at session start. It exists on disk, and the docs say it should auto-load alongside .claude/CLAUDE.md ("treated the same
way"), but Claude doesn't see it in initial context. Critically, the non-local sibling .claude/CLAUDE.md IS auto-loaded from the same .claude/ directory — so the loader
treats .claude/CLAUDE.md and .claude/CLAUDE.local.md asymmetrically. The local file's content only appears mid-session via system reminder if something causes the
harness to re-scan (e.g., a git pull that touches a sibling CLAUDE.md).

Project-root CLAUDE.local.md (not under .claude/) auto-loads correctly, so the bug is specific to the .claude/-nested location.

What Should Happen?

> "CLAUDE.md and CLAUDE.local.md files in the directory hierarchy above the working directory are loaded in full at launch."

> "For private per-project preferences that shouldn't be checked into version control, create a CLAUDE.local.md at the project root. It loads alongside CLAUDE.md and is
treated the same way."

So .claude/CLAUDE.local.md should be auto-loaded at session start, just like .claude/CLAUDE.md is. Instead, the loader is asymmetric:

| Location | Non-local (CLAUDE.md) | Local (CLAUDE.local.md) |
| --- | --- | --- |
| Project root | ✅ auto-loaded | ✅ auto-loaded |
| .claude/ subdir | ✅ auto-loaded | ❌ not auto-loaded |

The .claude/CLAUDE.local.md content does still appear mid-session via system reminder if something causes the harness to re-scan the directory (e.g., a git pull that
touches a sibling CLAUDE.md), but it isn't loaded at launch.

### Impact

In my session, the local file's contents (project-specific Slack-posting rules, including a "use slack_send_message_draft, not slack_send_message" rule) didn't influence
behavior earlier in the session because they weren't loaded — leading to four direct posts that violated those rules. Trust in the docs is broken when documented features
silently no-op for a specific path.

The docs ambiguity also confuses Claude itself: Claude originally created this CLAUDE.local.md at .claude/CLAUDE.local.md (mirroring the working .claude/CLAUDE.md
location) rather than at the project root. The docs say both "in the directory hierarchy above the working directory" (broad) and "at the project root" (specific), so the
model picked the location that mirrored the working sibling — which silently doesn't auto-load. Whether the fix is a code change (honor .claude/CLAUDE.local.md) or a docs
change (explicitly state the limitation), addressing it would prevent both user and Claude-the-model from being misled.

Error Messages/Logs

Steps to Reproduce

1. In a project at ~/copilot, create ~/copilot/.claude/CLAUDE.md (with any content) and ~/copilot/.claude/CLAUDE.local.md (with a different unique marker string, e.g.

MARKER_XYZ123).

1. Start a fresh Claude Code session in ~/copilot.
2. Ask Claude without using any tools whether it sees MARKER_XYZ123 in its loaded context — actual: it does not. (Asking about the non-local file's content works

correctly — .claude/CLAUDE.md IS loaded.)

1. Move the file to ~/copilot/CLAUDE.local.md (project root). Start another fresh Claude Code session in ~/copilot.
2. Ask the same question — actual: Claude now sees the marker in initial context. So root-level auto-load works; .claude/-nested doesn't.

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.1.121 (Claude Code)

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

VS Code integrated terminal

Additional Information

Related issues

• #54183 — "Support hidden config files (e.g. .claude/CLAUDE.md or .CLAUDE.md) for project-level instruction" — adjacent topic about hidden / nested config files

Ask

Either fix the loader to honor .claude/CLAUDE.local.md (matching .claude/CLAUDE.md's behavior), or update the docs to explicitly state that local files are only
auto-loaded from the project root, not from .claude/.

---

_Drafted with Claude Code (Opus 4.7)._