[FEATURE] Dynamically discover and load CLAUDE.md when navigating to new project directories
Preflight Checklist
- [x] I have searched existing requests and this feature hasn't been requested yet
- [x] This is a single feature request (not multiple features)
Problem Statement
When using Claude Code as a terminal-first workflow where the vast majority of computer interaction happens through the CLI, sessions often start from ~ (home directory) and navigate into different project directories as tasks evolve. Currently, the project context (CLAUDE.md, hooks, settings, auto memory) is locked at session launch and never re-evaluated, even when the agent navigates into a directory with its own CLAUDE.md.
This means project-specific instructions, coding standards, and conventions are invisible to Claude unless the user exits and restarts from the target directory. For users who treat the terminal as their primary interface, this creates constant friction: you either always know upfront which project you'll work in (and launch from there), or you lose project context entirely.
This is distinct from a /cd request. The working directory can stay anchored for file operations. The ask is specifically about instruction discovery: when Claude reads or writes files in a directory that contains a CLAUDE.md, those instructions should be loaded into context, regardless of where the session started.
Proposed Solution
When Claude navigates into (or operates on files within) a directory that contains a CLAUDE.md (or .claude/CLAUDE.md, .claude/rules/, .claude/settings.json), dynamically load those instructions into the session context. This extends the existing on-demand subdirectory CLAUDE.md loading behavior (which currently only works for subdirectories of the initial working directory) to work across project boundaries.
Concretely:
- If Claude
cds into~/project-b/or reads files there, and~/project-b/CLAUDE.mdexists, load it - If the directory has
.claude/rules/, discover and apply path-specific rules - If the directory has auto memory at
~/.claude/projects/<project>/memory/, load it - Show a notification when new instructions are loaded (similar to the existing
InstructionsLoadedhook event)
Use Case
Terminal-first workflow where a single Claude session spans multiple projects:
- Start Claude from
~(or a general-purpose directory) - User asks to work on project A: Claude navigates to
~/project-a/, picks up its CLAUDE.md - User pivots to project B: Claude navigates to
~/project-b/, picks up its CLAUDE.md - Each project's conventions, build commands, and coding standards are respected automatically
Without this, the user must exit and restart Claude from each project directory, losing conversation context and breaking flow.
Alternative Solutions
--add-dirwithCLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1partially addresses this but requires upfront knowledge of which directories will be needed- Exiting and restarting from the correct directory works but loses conversation context
/clearreloads settings but clears conversation history
Priority
Medium - Would be very helpful
Feature Category
Memory and context
Related Issues
- #31905 - Project context lost when Bash tool changes into nested git repository (closest existing bug)
- #24057 - MCP servers, hooks, and plugins should auto-reload when config changes (umbrella hot-reload request)
- #5513 - /reloadSettings command (popular request for manual reload)
- #33051 - Auto-loaded files change notifications
- #34135 - Agent creates files in CWD despite conversation context pointing to different project
- #33571 - Support starting Claude Code without a working directory (detached/global mode)
- #22652 - Support nested CLAUDE.local.md discovery in subdirectories
- #24987 - Subdirectory CLAUDE.md files not loaded on-demand (bug in documented behavior)
Note: Several /cd requests (#750, #19903) were closed as "not planned." This request is intentionally scoped differently: it's about dynamic instruction loading, not changing the working directory anchor for file operations.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗