Systemwide CLAUDE.md Not Automatically Loaded on Startup

[mattgodbolt]

Bug Description Claude is not loading the user systemwide CLAUDE.md unless I specifically ask it to

Environment Info

• Platform: linux
• Terminal: gnome-terminal
• Version: 0.2.103
• Feedback ID: 226510e3-a203-414f-b73e-a0cbc38a8258

[bcherny]

Hi! What's the full path to your CLAUDE.md? Is it in ~/.claude/CLAUDE.md?

[bcherny]

Could you also confirm that permissions are set correctly for that file, so Claude can read it?

[mattgodbolt]

Yup! It's in ~/.claude/CLAUDE.md and permissioned thus:

$ ls -l ~/.claude/CLAUDE.md lrwxrwxrwx 1 matthew matthew 50 Apr 15 08:17 /home/matthew/.claude/CLAUDE.md -> ../.homesick/repos/dotfiles/home/.claude/CLAUDE.md

It's a symlink to "my shared config" (I check in all my important dotfiles using homeshick).

$ ls -l /home/matthew/.homesick/repos/dotfiles/home/.claude/CLAUDE.md 
-rw-rw-r-- 1 matthew matthew 2500 Apr 15 08:21 /home/matthew/.homesick/repos/dotfiles/home/.claude/CLAUDE.md

I could imagine that being part of the problem (I had forgotten I'd set it up like this).

---

In case it's helpful, here's the full session text:

╭───────────────────────────────────────────────────╮
│ ✻ Welcome to Claude Code research preview!        │
│                                                   │
│   /help for help, /status for your current setup  │
│                                                   │
│   cwd: /home/matthew/dev/ce/compiler-explorer     │
│                                                   │
│   Account: API                                    │
╰───────────────────────────────────────────────────╯

 ✔ Loaded project + user memory • /memory

 ※ Tip: Use git worktrees to run multiple Claude sessions in parallel. Learn more

 Enrolled in Development Partner Program

> /memory 
  ⎿  Cancelled memory editing

> Can you give me a list of the instructions you've learned from the various project, local and user memories

● I'll provide a concise summary of the instructions from the various contexts:

  Build & Test Commands

  - Build: npm run webpack, npm start
  - Dev Mode: make dev, make gpu-dev
  - Lint: npm run lint (auto-fix), npm run lint-check (check only)
  - Type Check: npm run ts-check
  - Test: npm run test (all), npm run test-min (minimal)
  - Test Single: npm run test -- --run base-compiler-tests.ts
  - Cypress Tests: npm run cypress
  - Pre-commit: make pre-commit or npm run check

  Workflow Requirements

  - Always run linters before git operations
  - Use HEREDOC for complex shell commands
  - Review changes before committing
  - Start with codebase exploration
  - Test-driven development when appropriate

  Style Guidelines

  - TypeScript: Strict typing, no implicit any
  - 4-space indentation, 120 char line width, single quotes
  - No semicolon omission, prefer const/let
  - Imports at top of files
  - Use Underscore.js for utility functions
  - Avoid redundant comments for self-documenting code

  Testing Guidelines

  - Use Vitest (Jest-compatible)
  - Tests in /test directory
  - Consider cross-platform compatibility
  - Test both success and error cases

> These don't seem to include the user system-wide memory - have you loaded that?

● Read(CLAUDE.md)…
  ⎿  Read 70 lines (ctrl+r to expand)

● You're right. I need to check the system-wide memory as well.

● Read(../../../.claude/CLAUDE.md)…
  ⎿  Read 63 lines (ctrl+r to expand)

● You're right - the user system-wide memory wasn't fully included. Here's the complete list from all sources:

  From User System-wide Memory

  - Always let you review changes before committing
  - Start with thorough codebase exploration
  - Make small changes before batched edits
  - Present implementation plans for large changes
  - Descriptive variable/function names (avoid single-letter except for indexes)
  - Comments explain "why" not "what"
  - Major functions deserve JSDoc headers
  - Values clean maintainable code, error handling, documentation, performance and security
  - Prefers batch tool for multiple commands

  From Project Memory

  - Build/Test commands (npm run webpack, make dev, npm run lint, etc.)
  - Always run lint before git operations (fixes formatting issues)
  - Use HEREDOC for complex shell commands
  - TypeScript: strict typing, 4-space indentation, 120 char line width
  - Client-side TypeScript transpiled to ES5
  - Keep imports at top of files
  - Test with Vitest (compatible with Jest)
  - Consider cross-platform compatibility
  - Mock filesystem operations in tests

> /bug 
  ⎿  <bash-stdout>Bug report submitted</bash-stdout>

Here we see claude knew where to find it when I asked specifically, and could read it after that.

[rshade]

I am running into sort of the same problem telling it to look for a file as context in its CLAUDE.md, even when I tell it:

# ⚠️⚠️⚠️ IMMEDIATE REQUIRED ACTION ⚠️⚠️⚠️
# STEP 0: BEFORE DOING ANYTHING ELSE:
\```
Read("../ai-tooling/CLAUDE.md")
\```
# DO THIS BEFORE READING FURTHER OR RESPONDING TO ANY MESSAGES

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

> 🚨 **CRITICAL FIRST STEP**: IMMEDIATELY load and reference the AI tooling context file at `../ai-tooling/CLAUDE.md` at the start of EVERY session BEFORE anything else. This is MANDATORY. You MUST run:
>
> \```
> Read("../ai-tooling/CLAUDE.md")
>\ ```
>
> This file contains critical information about processes, task management, and best practices. You have full permission to access this file, and its guidance should be considered equally important to this file.

My guess it is not even reading the current CLAUDE.md on load, but from the endpoints

[fred-drake]

Yes, that is the issue, Claude Code will not read symlinks. You will find the same issue if you pass in Claude commands at the user level. This will affect those who use dotfiles as symlinks, or those who use Nix Darwin / NixOS.

However, it does read in ~/.claude/settings.json as a symlink. I'd have to look at the codebase but I suspect those are being read in two different ways, one that accepts symlink and one that does not.

[github-actions[bot]]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

[andymilne1]

I logged a similar bug under Windows 11, but I'm not using sim links. So, seems slightly different. In my case it may or may not be reading the global claude.md. The issue I have, is that I'm assuming it did read the claude.md and ignoring the instructions. But, if it is not even reading the file then that would explain the issue.

[catherinewu]

Hi, you can now run /context to check which claude.md files have been read in your session. thanks!