SegfaultSorcerer/heap-seance

Summoning retained objects from the heap — so you can interrogate what refuses to die.
An MCP server + CLI toolkit that channels the spirits of jcmd , jmap , jstat , jfr , Eclipse MAT, and async-profiler into a structured leak investigation workflow — designed to run inside Claude Code .
2 slash commands. 8 MCP tools. Conservative by default.
---
How It Works •
Quick Start •
MCP Tools •
Workflow •
Prerequisites •
Contributing
---
How It Works
Heap Seance follows a two-stage escalation model. No deep forensics unless the evidence demands it.
**Confidence is earned, not assumed.** high requires at least two independent strong signals. A single growing class is watch. Growth plus GC pressure is suspicious. Add a MAT dominator or JFR correlation and you get probable_memory_leak.
Quick Start
Requires uv, Python 3.10+, and a JDK 17+ for tooling (the target app can run any Java version).
1. Clone
2. Add .mcp.json to your Java project
In the project you want to investigate, create a .mcp.json:
--directory points to where you cloned Heap Seance. uv run handles the virtual environment and dependencies automatically. ASYNC_PROFILER_BIN is optional — if missing, deep mode continues with JFR + MAT.
3. Copy the Claude Code commands
Copy the .claude/commands/ folder into your Java project so the /leak-scan and /leak-deep slash commands are available:
4. Run
Heap Seance resolves the target process, collects evidence, and returns a structured verdict.
MCP Tools
| Tool | What it does |
|------|-------------|
| java_list_processes() | Discover running JVMs via jcmd -l |
| java_class_histogram(pid) | Snapshot live object counts per class |
| java_gc_snapshot(pid) | Sample jstat -gcutil over time |
| java_jfr_start(pid) | Capture a JFR recording |
| java_jfr_summary(jfr_file) | Summarize JFR event types and counts |
| java_heap_dump(pid) | Full heap dump (.hprof) |
| java_mat_suspects(heap_dump) | Run MAT leak suspects analysis |
| java_async_alloc_profile(pid) | Allocation flame graph via async-profiler |
Every tool returns the same unified schema:
Investigation Workflow
1. **Start your app** and let it initialize fully.
2. **/leak-scan ** — takes the first histogram snapshot.
3. **Exercise the suspect behavior** — the scan prompts you between each of the 3 histogram samples to perform the action you suspect is leaking (open/close views, send requests, repeat workflows). This is critical — without load between samples, leaks stay invisible.
4. **Read the verdict.** Focus on Confidence, Key Evidence, Suspect Types.
5. **/leak-deep ** if the scan flags growth, or if you want full forensics regardless.
6. **Fix and re-scan.** Bounded caches, weak refs, listener cleanup — then /leak-scan again to confirm the signal drops.
7. **Keep artifacts.** .jfr, .hprof, and MAT reports are saved for team review.
What you get back
**/leak-scan** returns: Verdict, Confidence, Key Evidence, Suspect Types, Artifacts, Next Steps.
**/leak-deep** goes further: Verdict, Confidence, Root Holder Hypothesis (who retains the growing objects and via which field/chain), Supporting Evidence, Artifacts, Remediation Hypotheses (concrete fix suggestions), Verification Plan.