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:
- Setup screen appears - App should detect missing hooks
- Hook installation works - Click install, verify success
- 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