Symlinked settings.json causes permission failures and severe performance degradation

Claude Code Bug Report: Symlinked settings.json Not Properly Recognized

Summary

Claude Code fails to properly recognize permissions from a symlinked ~/.claude/settings.json file, causing both permission recognition failures and severe performance degradation.

Environment

• Claude Code Version: Latest (as of 2025-07-15)
• Operating System: macOS Darwin 24.5.0
• Shell: Zsh

Bug Description

When ~/.claude/settings.json is a symbolic link pointing to another file, Claude Code exhibits two critical issues:

1. Permission Recognition Failure: Commands that are explicitly allowed in the global settings file trigger permission prompts
2. Performance Degradation: Simple commands like ls, cat, and echo experience significant delays (several seconds) before execution

Steps to Reproduce

1. Create a valid settings file with global permissions:

{
  "permissions": {
    "allow": [
      "Bash(ls:*)",
      "Bash(cat:*)",
      "Bash(echo:*)",
      "Bash(pwd:*)",
      "Bash(git:*)"
    ]
  }
}

1. Create a symlink for ~/.claude/settings.json:

ln -s /path/to/actual/settings.json ~/.claude/settings.json

1. Use Claude Code to run simple commands like ls, cat README.md, or git status

1. Observe:

• Permission prompts appear for commands that should be allowed
• Commands take several seconds to execute (vs instant execution)

Expected Behavior

• Claude Code should follow the symlink and read permissions from the target file
• Commands listed in the global allow list should execute without permission prompts
• Command execution should be instant for simple operations

Actual Behavior

• Claude Code appears to not properly read permissions from symlinked settings files
• Every command triggers a permission prompt, even those explicitly allowed
• Command execution is severely delayed (multiple seconds for simple commands)

Workaround

Replace the symlink with an actual copy of the file:

rm ~/.claude/settings.json
cp /path/to/actual/settings.json ~/.claude/settings.json

This immediately resolves both issues - permissions are recognized and performance returns to normal.

Impact

This bug prevents users from:

• Using centralized configuration management (dotfiles repositories)
• Sharing settings across multiple machines via symlinks
• Following standard Unix configuration practices

Additional Context

Many developers use dotfile management systems (like GNU Stow, chezmoi, or custom scripts) that rely on symlinks to manage configuration files. This bug forces users to either:

1. Manually copy settings files (losing centralized management)
2. Create synchronization scripts (adding complexity)
3. Accept the permission prompts and performance issues

Test Results

• Symlink target is valid JSON: ✓
• Symlink target is readable by standard tools: ✓
• File permissions are correct: ✓
• Same content works when copied instead of symlinked: ✓

This appears to be an issue with how Claude Code specifically reads or caches the settings file when it's a symlink.