Quick Start doesn’t call out that .claude/settings.json likely needs local edits (e.g. PAI_DIR), leading to confusing hook failures

[mellanon]

Context
The Quick Start in README.md focuses on:

# Clone the repository
git clone https://github.com/danielmiessler/Personal_AI_Infrastructure.git
cd Personal_AI_Infrastructure

# Copy environment template
cp .claude/.env.example .claude/.env

# Copy .claude directory to your home directory
cp -r .claude ~/.claude

but doesn’t mention that:

• ~/.claude/settings.json is a critical configuration file for hooks and environment,
• Values like PAI_DIR may need to be adjusted per user/machine.

This makes it easy for new users to end up with working files under ~/.claude, but failing hooks (e.g. unexpanded $HOME paths) and no obvious pointer toward settings.json as the place to fix it.

Observed behavior
After following the Quick Start verbatim, hooks can fail with messages like:
/bin/sh: $HOME/.claude/hooks/capture-all-events.ts: No such file or directory

• The root cause is often a mismatch between:

  • The actual location of .claude/hooks on disk, and
  • The PAI_DIR value in ~/.claude/settings.json.

• Fixing PAI_DIR to an absolute path in settings.json resolves the issue, but this isn’t hinted at in the Quick Start.

[danielmiessler]

Thanks for the detailed investigation! You've identified a real issue with environment variable expansion.

Root Cause:
Claude Code doesn't expand $HOME in the JSON env section when executing hooks via /bin/sh. The literal string "$HOME/.claude" is passed to the hooks.

Investigation:
Looking at the hook code, ALL hooks have this pattern:

const paiDir = process.env.PAI_DIR || join(homedir(), '.claude');

This means hooks default to ~/.claude if PAI_DIR isn't set or is invalid.

Proposed Fix:
The cleanest solution is to remove PAI_DIR from settings.json and let the hooks use their built-in default. This avoids the expansion issue entirely.

Changes I'm making:

1. Remove PAI_DIR from .claude/settings.json env section
2. Update QUICKSTART.md to document this (and add troubleshooting note)
3. Add comment in settings.json explaining why PAI_DIR isn't needed

Alternative (if you need custom PAI_DIR):
If you DO need a custom location, use an absolute path:

"PAI_DIR": "/Users/yourusername/.claude"

Let me implement this fix now and we can close this issue.

[danielmiessler]

This has been fixed in commit b69a20b!

The Solution:
Removed PAI_DIR from settings.json entirely. The hooks automatically default to ~/.claude when PAI_DIR isn't set, avoiding the expansion issue completely.

Changes Made:

1. ✅ Removed "PAI_DIR": "$HOME/.claude" from settings.json
2. ✅ Added explanatory comment about when PAI_DIR is needed
3. ✅ Updated QUICKSTART.md with troubleshooting section for this exact error

How to Update:

cd ~/Personal_AI_Infrastructure
git pull origin main
cp -r .claude ~/.claude  # This will update your settings.json

If You Need Custom PAI_DIR:
Only set it if you're using a non-standard location, and use an absolute path:

"PAI_DIR": "/Users/yourname/my-custom-location"

Otherwise, just don't set it at all - the hooks work perfectly without it!

Closing as fixed. Thanks for the detailed investigation!

[danielmiessler]

Thanks for flagging this @1activegeek - you're right, the fix was inadvertently reverted.

What happened:

• Original fix (b69a20b) removed PAI_DIR to avoid expansion issues
• Later commit (9647d9e) restored PAI_DIR for location flexibility
• But the placeholder /Users/YOURNAME/.claude requires manual editing

The fix (coming in next commit):

1. Updated setup.sh to automatically replace the placeholder with your actual home directory path
2. Added clearer documentation in settings.json explaining the issue
3. Setup script now copies files AND updates PAI_DIR in one step

If you're hitting this now:
Edit ~/.claude/settings.json and change:

"PAI_DIR": "/Users/YOURNAME/.claude"

to:

"PAI_DIR": "/Users/YOUR_ACTUAL_USERNAME/.claude"

Or re-run bash .claude/setup.sh after the fix is pushed.

Thanks for the detailed report - this helps make PAI better for everyone!