Permission rules: $HOME not expanded during startup validation when checking symlinked config
Issue
During startup validation, Claude Code resolves symlinks to their absolute paths before evaluating permission rule variables. This causes $HOME to not be expanded in permission rules when the target is a symlink.
Current Behavior
Permission rule:
Read($HOME/cloud/shared-source/Claude/proj_template/**)Results in permission prompt for reading ./.claude/settings.json (which is symlinked to that path) because the symlink is resolved to /Users/jaclu/cloud/shared-source/... first, then checked against the rule containing the literal string $HOME/....
Workaround
Must use explicit absolute paths for each platform:
Read(//Users/jaclu/cloud/shared-source/Claude/proj_template/**)
Read(//home/jaclu/cloud/shared-source/Claude/proj_template/**)This violates single-point-of-truth principle when config is shared across platforms via symlinks.
Expected Behavior
Permission rule variables like $HOME should be expanded before or during symlink resolution, not after, so they work consistently for symlinked config files.
3 Comments
Permission rules don't expand environment variables such as
$HOME— the rule text is matched literally, soRead($HOME/...)never matches anything. For a home-relative path use the documented~/prefix, which resolves to your home directory on both macOS and Linux and therefore also matches the resolved symlink target:The four supported path forms (
//pathabsolute,~/pathhome,/pathrelative to the settings file,pathrelative to the current directory) are listed here: https://code.claude.com/docs/en/permissions#read-and-editClosing as answered by the docs — reply here if the
~/form still prompts for the symlinked file and we'll reopen.🤖 Generated with Claude Code
---
_Generated by Claude Code_
Not meant as a complaint or anything, more a curiosity. I asked claude repeatedly about this and to check online docs to ensure it reported on documented features, and my (current) one each time told me that ~ could not be used in .claude/settings.json
This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.