Linux case-sensitivity issue: Claude Code expects lowercase directories

[chrisplough]

Hola! I ran into this, when deploying PAI on both macos and linux (Omarchy) environments. Worked on macos, but not linux and was a head-scratcher for a bit.

Description

Claude Code looks for lowercase directory names (skills, commands, tools, etc.) but PAI uses TitleCase (Skills, Commands, Tools). This works on macOS with a case-insensitive (ish) filesystem but fails on Linux which is more strictly case-sensitive.

Claude Code silently creates lowercase directories when it can't find TitleCase ones, leading to:

• Skills not being recognized
• Slash commands not working (/pa, /paiupdate)
• Hooks not executing
• History not being captured properly

Environment

• OS: Arch Linux (Omarchy)
• Filesystem: btrfs (case-sensitive)
• Claude Code version: 2.0.70 (and 2.0.75 on macos)
• PAI version: Fresh clone as of 2025-12-22 (tried multiple clones to ensure it wasn't on my side)

Directories requiring symlinks

At ~/.claude/ level:

ln -s Commands commands
ln -s Skills skills
ln -s Tools tools
ln -s History history
ln -s Agents agents
ln -s Hooks hooks
ln -s Scratchpad scratchpad

Inside ~/.claude/History/:

ln -s Raw-Outputs raw-outputs
ln -s Sessions sessions

Note: There may be additional directories I haven't discovered yet.

Temporary workaround

After cloning PAI, run:

cd ~/.claude
ln -s Commands commands
ln -s Skills skills
ln -s Tools tools
ln -s History history
ln -s Agents agents
ln -s Hooks hooks
ln -s Scratchpad scratchpad

cd ~/.claude/History
ln -s Raw-Outputs raw-outputs
ln -s Sessions sessions

Suggested fix

Either:

1. Rename PAI directories to lowercase to match what Claude Code expects
2. Document the symlink requirement for Linux users in the README/QUICKSTART

Reproduction steps

1. Fresh install PAI on Linux (case-sensitive filesystem)
2. Run claude
3. Try /pa or /paiupdate - fails with "Unknown slash command"
4. Try use fabric to summarize "test" - fails with "Unknown skill: Fabric"
5. Create symlinks per workaround above
6. Commands and skills now work

[pybe]

I've been bashing my head against this for a little while. I was going mad. Couldn't work out why my configuration and install wasn't working. The symlink idea is simple, but it kind of drives me a little crazy thinking about all the duplicated folders. I might just ask Claude to convert everything to lowercase. And then update all of the relevant files. Wish me luck!

[pybe]

Claudes take on things:

ANALYSIS:

Official Claude Code Expectations

Per https://code.claude.com/docs/en/skills:

• Skills: ~/.claude/skills/ (lowercase)
• Commands: ~/.claude/commands/ (lowercase)
• This is hardcoded - no configuration option exists

PAI's Intentional Design Choice

PAI repository uses TitleCase deliberately:
~/.claude/
├── Skills/ (not skills/)
├── Commands/ (not commands/)
├── Agents/
├── Hooks/
├── History/
└── Tools/

Known Issues on PAI GitHub

Issue	Description
#239	"Linux case-sensitivity: Claude Code expects lowercase directories"
#237	Hook references raw-outputs but directory is Raw-Outputs
#229	"Critical: Workflow references broken due to case mismatch"

Open PRs Addressing This

• https://github.com/danielmiessler/PAI/pulls - "Standardize TitleCase naming across all Skills"
• https://github.com/danielmiessler/PAI/pulls - "Rename Raw-Outputs to RawOutputs for consistent PascalCase"

The Core Conflict

PAI's philosophy: TitleCase for visual clarity and organization
Claude Code's reality: Hardcoded lowercase paths for auto-discovery

The issue notes that macOS (case-insensitive) masks this problem, but Linux exposes it.

RESULTS: We're not doing anything "wrong" - PAI intentionally diverged from Claude Code conventions. The community is actively discussing solutions.

STATUS: Known upstream issue with no official resolution yet.

CAPTURE: PAI uses TitleCase by design; Claude Code expects lowercase. GitHub issues #239, #237, #229 document this. PRs #236, #238 work on standardization but don't resolve the Claude Code compatibility.

NEXT: Three paths forward:

1. Wait for PAI upstream - See if they resolve this officially
2. Create symlinks - ln -s Skills skills etc. (recommended workaround in issues)
3. Rename to lowercase - Full Claude Code compatibility but diverges from PAI convention

STORY EXPLANATION:

1. Claude Code officially expects lowercase skills/ and commands/ directories
2. PAI project intentionally uses TitleCase Skills/ and Commands/
3. This is a known conflict documented in GitHub issues Linux case-sensitivity issue: Claude Code expects lowercase directories #239, Hooks use lowercase 'raw-outputs' but directory is 'Raw-Outputs' (breaks on Linux) #237, Critical: Workflow references broken due to case mismatch #229
4. macOS hides the problem (case-insensitive); Linux exposes it
5. Open PRs fix: Standardize TitleCase naming across all Skills #236 and fix: Rename Raw-Outputs to RawOutputs for consistent PascalCase naming #238 standardize TitleCase within PAI but don't fix Claude Code compatibility
6. The community workaround is creating symlinks from lowercase to TitleCase
7. No configuration exists to make Claude Code use TitleCase paths
8. We correctly updated PAI docs to use consistent TitleCase - the Claude Code incompatibility is upstream

COMPLETED: Confirmed case mismatch is known PAI issue; symlinks are the documented workaround.

Sources:

• https://code.claude.com/docs/en/skills
• https://github.com/danielmiessler/PAI
• Linux case-sensitivity issue: Claude Code expects lowercase directories #239

[pybe]

Chickened out on the change to lowercase when I read 1 in the execution order.... Symlinks here I come.

Here is Claude's plan:
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
Plan: Convert PAI to Lowercase Directory Convention

Objective

Rename all TitleCase directories in ~/.claude/ to lowercase to conform with Claude Code's expected conventions, then update all path references in configuration and
documentation files.

---

Execution Order

1. Close any active Claude Code sessions
2. Phase 1: Rename top-level directories
3. Phase 2: Rename nested directories
4. Phase 3: Update all file references (batch sed)
5. Phase 4: Update PersonalAssistant references
6. Phase 5: Verify and test
7. Commit changes to git

[pybe]

OK so it seems like we might only need skills and commands?

Claude plan:

Plan: Create Symlinks for Claude Code Compatibility

Objective

Create lowercase symlinks pointing to TitleCase directories so Claude Code's auto-discovery works while keeping PAI's TitleCase convention.

Symlinks to Create

cd ~/.claude
ln -s Skills skills
ln -s Commands commands

That's it - just 2 symlinks needed for Claude Code compatibility.

Why Only 2?

• Claude Code only auto-discovers from skills/ and commands/
• Other directories (Hooks, History, Agents, etc.) work via explicit paths in settings.json

[sti0]

This was already addressed and closed due to a elementary changes of the system. #226. See #222 for more details.