npx claudepluginhub meta-quest/agentic-tools --plugin meta-vrThis skill is limited to using the following tools:
Use this skill when you need hardware-level CPU performance insights on Meta Quest devices:
Analyzes Perfetto traces for Meta Quest and Horizon OS VR performance: frame timing, CPU/GPU bottlenecks, render pass analysis. For profiling frame drops, jank, thermal throttling.
Guides performance profiling of Apple platform apps using Instruments, diagnosing hangs, stutters, memory leaks, slow launches, and energy drain. For app reviews and bottleneck investigations.
Profiles iOS app performance with Instruments: Time Profiler for CPU, Allocations and Leaks for memory, Network for traffic, Energy Log for battery impact. Optimizes launch times, scrolling, and energy use.
Share bugs, ideas, or general feedback.
Use this skill when you need hardware-level CPU performance insights on Meta Quest devices:
This skill complements hz-perfetto-debug. Perfetto shows what your app is doing over time. Simpleperf shows where the CPU is spending hardware cycles — cache misses, branch mispredictions, and instruction throughput that Perfetto can't see.
Quest devices run on mobile ARM SoCs with strict thermal and power budgets. CPU-bound apps hit frame drops when:
| Refresh Rate | CPU Frame Budget | Notes |
|---|---|---|
| 120 Hz | 8.3 ms | Tight — simpleperf critical for finding hotspots |
| 90 Hz | 11.1 ms | Default target for most apps |
| 72 Hz | 13.9 ms | Fallback for heavier apps |
Simpleperf's hardware counters reveal bottlenecks invisible to software tracing.
Simpleperf profiling is powered by the hzdb CLI. Invoke via npx — no install required:
npx -y @meta-quest/hzdb --version
Examples below use the bare hzdb command for brevity — substitute npx -y @meta-quest/hzdb. Connect your Quest via USB with developer mode enabled.
Before optimizing, determine the bottleneck type:
# Classify the foreground app's workload (10-second sample)
hzdb perf simpleperf classify
# Target a specific app
hzdb perf simpleperf classify --app com.example.myapp
# Custom duration
hzdb perf simpleperf classify --duration 15
Returns a classification with evidence:
| Classification | Indicator | Optimization Strategy |
|---|---|---|
| CPU-bound | High IPC, low stall ratio | Optimize algorithms, reduce draw calls, batch work |
| Memory-bound | High stall ratio (stalled-cycles-backend / cpu-cycles) | Reduce cache misses, improve data locality, shrink working set |
| I/O-bound | High context switches per second | Reduce blocking I/O, use async, minimize thread contention |
Capture a CPU cycle profile to find the most expensive functions:
# Record CPU hotspots for the foreground app
hzdb perf simpleperf record
# Custom frequency and duration
hzdb perf simpleperf record --frequency 4000 --duration 10
# Target a specific app
hzdb perf simpleperf record --app com.example.myapp
The recording samples CPU cycles at the specified frequency (default 4000 Hz) and generates a profile showing which functions consume the most CPU time.
Determine how much CPU time is spent in kernel vs userspace per thread:
# Measure kernel overhead for the foreground app
hzdb perf simpleperf kernel-overhead
# Custom duration
hzdb perf simpleperf kernel-overhead --app com.example.myapp --duration 10
Returns per-thread breakdown of user-mode vs kernel-mode CPU cycles. High kernel overhead (>20%) in a thread suggests:
Always start with classification. This prevents wasting time optimizing the wrong thing.
hzdb perf simpleperf classify --app com.example.myapp --duration 10
Decision tree based on results:
hzdb perf simpleperf record --app com.example.myapp --duration 10
Review the top functions by CPU cycle consumption. Common VR hotspots:
| Function Pattern | Likely Cause | Fix |
|---|---|---|
Physics.* / PhysX | Complex physics simulation | Reduce collider count, simplify meshes, increase fixed timestep |
Render* / Draw* | Too many draw calls | Batch materials, use GPU instancing, reduce unique materials |
GC_* / gc_alloc | Garbage collection pressure | Pool allocations, avoid per-frame allocations |
memcpy / memmove | Large data copies | Use references, reduce buffer sizes, avoid unnecessary copies |
LZ4_* / compress | Asset decompression | Pre-decompress, use lighter compression, cache results |
If classification shows memory-bound, the issue is likely cache misses or memory bandwidth:
Use Perfetto hz-perfetto-debug to correlate memory-bound regions with specific code paths.
hzdb perf simpleperf kernel-overhead --app com.example.myapp
Interpreting results by thread:
| Thread | Expected Kernel % | High Kernel % Indicates |
|---|---|---|
| Main/Game thread | < 5% | Excessive file I/O, logging, or allocations |
| Render thread | 5-15% | Normal (GPU driver overhead). >20% = driver issue |
| Worker threads | < 5% | Thread synchronization overhead |
| Audio thread | < 10% | Normal for audio HAL calls |
Simpleperf tells you where cycles go. Perfetto tells you when and in what context. Use together:
hzdb perf capture) shows when those functions run relative to frame boundarieshzdb perf query to correlate function timing with frame dropshzdb device info.adb shell simpleperf fails, ensure developer mode is enabled and USB debugging is authorized.For detailed guides on specific topics, see: