heap-seance: Command for Claude Code

Run full deep Java leak forensics for $ARGUMENTS.

Interpret $ARGUMENTS as either a PID (integer) or a process name/pattern (string).

This command runs deep evidence collection unconditionally — it does not wait for scan signals to justify escalation. Use it when you already suspect a leak or want comprehensive evidence.

Step 1: Resolve target process

• If $ARGUMENTS is an integer, use it directly as PID.
• If $ARGUMENTS is empty, call java_list_processes() and list all discovered JVMs so the user can choose. Do not pick one silently.
• If $ARGUMENTS is a string, call java_list_processes() and match by substring against each process display field (case-insensitive). If exactly one process matches, use it. If multiple match, list them and ask the user to narrow down. If none match, report this and stop.

Step 2: Capture baseline signals

These establish the growth and GC context that deep tools will corroborate or refute.

1. Collect 3 histogram samples with java_class_histogram(pid, live_only=true). Between each sample, ask the user to perform the suspected leaking action in their application (e.g., open/close a view, send requests, load/discard data) and confirm when done. Without exercising the app between snapshots, leaks stay invisible. This gives the monotonic growth baseline — classes whose retained bytes rise across all 3 snapshots are candidates.
2. Collect GC snapshot with java_gc_snapshot(pid, interval_s=2, samples=6). This reveals whether old-gen is under pressure and Full GCs are occurring.

Step 3: Deep evidence collection

Run all of these unconditionally, in sequence:

1. JFR recording: java_jfr_start(pid, profile="profile", duration_s=45) — captures allocation events, GC activity, and object count data over 45 seconds.
2. JFR summary: java_jfr_summary(jfr_file) — extracts event types and counts. Look for jdk.ObjectCountAfterGC events and whether growth candidate classes appear in allocation-heavy events.
3. Heap dump: java_heap_dump(pid, live_only=true) — full reachable-object snapshot. live_only=true triggers GC first so the dump contains only retained objects, making dominator analysis cleaner.
4. MAT leak suspects: java_mat_suspects(heap_dump_file) — runs Eclipse MAT's automated leak suspect analysis. This is the strongest signal: it identifies dominator holders, accumulation points, and retained byte chains.
5. Allocation profile: java_async_alloc_profile(pid, duration_s=30) — flame graph of allocation hot spots. Only if async-profiler is available. Useful as tie-breaker when MAT and JFR are ambiguous.