Claude HUD Manual Testing

Claude HUD 手动测试

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"

完成重要功能开发后
修复状态检测Bug后
提交影响会话跟踪的代码前
用户要求“测试应用”或“验证应用可正常运行”时

Testing Workflow

测试工作流

1. Full Reset

1. 完全重置

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

bash

./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

重置至干净状态，以测试首次运行体验并验证没有功能依赖于过期数据：

bash

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

该脚本会清除：

应用UserDefaults（布局、设置状态）
```
~/.capacitor/
```
（会话、锁、活动记录）
Hook脚本及注册信息
重新构建并启动应用

2. First-Run Verification

2. 首次运行验证

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

重置完成后，验证引导流程：

显示设置界面 - 应用应检测到缺失的hooks
Hook安装正常 - 点击安装，验证安装成功
项目列表为空 - 尚未固定任何项目

3. Core Functionality Checklist

3. 核心功能检查清单

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

手动测试各项功能：

功能	测试方法	预期结果
添加项目	点击+，选择项目文件夹	项目出现在列表中
会话检测	在该项目中启动Claude	状态显示为就绪/工作中
状态转换	输入提示词，等待响应	工作中 → 就绪状态正常转换
锁检测	执行 `ls ~/.capacitor/sessions/`	Claude运行时锁目录存在
会话结束	退出Claude会话	状态返回至空闲

4. Debug Commands

4. 调试命令

If issues occur, check these:

bash

undefined

若出现问题，执行以下命令排查：

bash

undefined

Watch hook events in real-time

实时监控Hook事件

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)"

undefined

ps aux | grep -E "(claude|hud-hook)"

undefined

5. Quick Restart (No Reset)

5. 快速重启（不重置）

For iterative testing without full reset:

bash

./scripts/dev/restart-app.sh

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

用于无需完全重置的迭代测试：

bash

./scripts/dev/restart-app.sh

该脚本会重新构建Rust + Swift并重启应用，保留现有状态。

Common Issues

常见问题

State stuck on Working/Waiting

状态卡在工作中/等待中

Check if lock holder is alive:

bash

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.

检查锁持有进程是否存活：

bash

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

若PID已终止但锁仍存在，下次应用启动时清理流程应自动移除该锁。

Hook events not firing

Hook事件未触发

Verify hooks are registered:

bash

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

Should show entries for SessionStart, UserPromptSubmit, etc. pointing to

hud-state-tracker.sh

.

验证hooks已注册：

bash

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

应显示指向

hud-state-tracker.sh

的SessionStart、UserPromptSubmit等条目。

UniFFI checksum mismatch

UniFFI校验和不匹配

Regenerate bindings:

bash

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

重新生成绑定：

bash

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

测试完成后，确认以下项：

应用启动无崩溃
Hooks在首次运行时安装成功
项目可正常添加/移除
会话状态准确反映Claude的活动情况
状态转换正常（空闲 → 就绪 → 工作中 → 就绪 → 空闲）
无孤立锁持有者堆积

hud-manual-testing

Original

Translation

Claude HUD Manual Testing

Claude HUD 手动测试

When to Use

适用场景

Testing Workflow

测试工作流

1. Full Reset

1. 完全重置

2. First-Run Verification

2. 首次运行验证

3. Core Functionality Checklist

3. 核心功能检查清单

4. Debug Commands

4. 调试命令

Watch hook events in real-time

实时监控Hook事件

View current session states

查看当前会话状态

Check active locks

检查活动锁

Check for process

检查进程

5. Quick Restart (No Reset)

5. 快速重启（不重置）

Common Issues

常见问题

State stuck on Working/Waiting

状态卡在工作中/等待中

Hook events not firing

Hook事件未触发

UniFFI checksum mismatch

UniFFI校验和不匹配

Verification Summary

验证总结