Claude HUD Manual Testing

Verify core functionality works after code changes. Uses the project's reset script and debugging tools.

When to Use

• After implementing significant features
• After fixing state detection bugs
• Before commits affecting session tracking
• When user asks to "test the app" or "verify it works"

Testing Workflow

1. Full Reset

Reset to clean state to test first-run experience and verify nothing depends on stale data:

./scripts/dev/reset-for-testing.sh

This clears:

• App UserDefaults (layout, setup state)
• ~/.capacitor/ (sessions, locks, activity)
• Hook script and registrations
• Rebuilds app and launches it

2. First-Run Verification

After reset, verify the onboarding flow:

1. Setup screen appears - App should detect missing hooks
2. Hook installation works - Click install, verify success
3. Empty project list - No projects pinned yet

3. Core Functionality Checklist

Test each feature manually:

Feature	How to Test	Expected
Add project	Click +, select a project folder	Project appears in list
Session detection	Start Claude in that project	State shows Ready/Working
State transitions	Type prompt, wait for response	Working → Ready transitions
Lock detection	Check ls ~/.capacitor/sessions/	Lock dir exists while Claude runs
Session end	Exit Claude session	State returns to Idle

4. Debug Commands

If issues occur, check these:

# Watch hook events in real-time
tail -f ~/.capacitor/hud-hook-debug.log

# View current session states
cat ~/.capacitor/sessions.json | jq .

# Check active locks
ls -la ~/.capacitor/sessions/

# Check for process
ps aux | grep -E "(claude|hud-hook)"

5. Quick Restart (No Reset)

For iterative testing without full reset:

./scripts/dev/restart-app.sh

This rebuilds Rust + Swift and restarts the app, keeping state intact.

Common Issues

State stuck on Working/Waiting

Check if lock holder is alive:

cat ~/.capacitor/sessions/*.lock/pid | xargs -I {} ps -p {}

If PID is dead but lock exists, the cleanup should remove it on next app launch.

Hook events not firing

Verify hooks are registered:

cat ~/.claude/settings.json | jq '.hooks'

Should show entries for SessionStart, UserPromptSubmit, etc. pointing to hud-state-tracker.sh.

UniFFI checksum mismatch

Regenerate bindings:

cargo build -p hud-core --release
cd core/hud-core && cargo run --bin uniffi-bindgen generate --library ../../target/release/libhud_core.dylib --language swift --out-dir ../../apps/swift/bindings/
cp ../../apps/swift/bindings/hud_core.swift ../../apps/swift/Sources/ClaudeHUD/Bridge/
rm -rf ../../apps/swift/.build

Verification Summary

After testing, confirm:

• App launches without crash
• Hooks install successfully on first run
• Projects can be added/removed
• Session states reflect actual Claude activity
• States transition correctly (Idle → Ready → Working → Ready → Idle)
• No orphaned lock holders accumulate