heap-seance

Heap Seance Introduction

Purpose

Heap Seance is an MCP server + CLI toolkit for memory leak investigation in Java applications. It chains together JVM forensic tools such as jcmd, jmap, jstat, jfr, Eclipse MAT, and async-profiler into a structured workflow, designed to run within Claude Code, consolidating scattered tool output into a unified leak verdict conclusion.

Main Capabilities

• Provides 2 slash commands (/leak-scan, /leak-deep) and 8 MCP tools.
• Uses a two-stage escalation model: conservative scan and deep forensics; deep analysis is not performed without sufficient evidence.
• All tools return the same unified schema.
• Confidence grading: high-risk conclusions require at least two independent strong signals; a single continuously growing class is watch (observation); growth combined with GC pressure is suspicious (suspicious); only with the addition of MAT dominator tree or JFR correlation evidence is it judged as probable_memory_leak (probable memory leak).
• /leak-scan returns: Verdict (verdict), Confidence (confidence), Key Evidence (key evidence), Suspect Types (suspect types), Artifacts (artifacts), Next Steps (next steps).
• /leak-deep additionally returns: Root Holder Hypothesis (root holder hypothesis, i.e. who holds the growing object through which field/chain), Supporting Evidence (supporting evidence), Remediation Hypotheses (specific remediation suggestions), Verification Plan (verification plan).
• Retains artifacts such as .jfr, .hprof, and MAT reports for team review.

Usage

Prerequisites: requires uv, Python 3.10+, and JDK 17+ for the toolchain (the target application can run any Java version).

1. Create .mcp.json in the Java project to be investigated, where --directory points to the location where Heap Seance is cloned; uv run automatically handles the virtual environment and dependencies. ASYNC_PROFILER_BIN is optional; when missing, deep mode continues using JFR + MAT.
2. Copy the .claude/commands/ folder into the Java project to use the /leak-scan and /leak-deep slash commands.
3. Investigation workflow: start the application and let it complete initialization; run /leak-scan <name-or-pid> to get the first histogram snapshot; between the three histogram samples, perform the suspected leak behavior as prompted (e.g. open/close views, send requests, repeat workflows)—without load between samples the leak is not visible; read the verdict, paying attention to Confidence, Key Evidence, Suspect Types; if the scan flags growth or you want complete forensics, run /leak-deep <name-or-pid>; after fixing, rescan to confirm the signal decreases.

Command-line usage is also supported outside Claude Code. Environment variables can be set in the env block of .mcp.json, or as shell variables; the CLI flags --sse and --streamable-http can replace MCP_TRANSPORT. See .mcp.json.example for the full configuration template.

Toolchain requirements: JDK 17+ for jcmd, jmap, jstat, set via JAVA_HOME in .mcp.json; the target application can run any Java version (including Java 8). Deep forensics requires Eclipse MAT CLI (ParseHeapDump.sh / .bat); async-profiler is an optional tie-breaker tool; the jfr CLI is optional and used for JFR summaries (if unavailable, it falls back to jcmd JFR.view; Java 8 targets skip JFR entirely due to format incompatibility). You can check the environment configuration with the available commands.

Applicable Scenarios

• Preliminary scanning and deep root cause analysis of memory leaks in Java applications within Claude Code.
• Leak investigation workflows that need to be reproducible, with confidence grading and artifact retention.
• Verifying that signals decrease after a fix.

Limitations and Compatibility

• Java 8 targets: histogram + GC + MAT work fully; JFR is skipped due to the v0.9 format being incompatible with modern tools..
• Windows: MAT works through ParseHeapDump.bat; async-profiler is optional, and when missing, deep mode continues to use JFR + MAT; region-specific decimal separators (comma and dot) in jstat output are handled automatically.
• MAT + JAVA_HOME: MAT is launched using the JDK in JAVA_HOME, so it can run even if the system default Java is too old.
• The project is dual-licensed: Apache License, Version 2.0.
• See CONTRIBUTING.md for contribution guidelines.
• The repository also includes Java example scenarios for verification (real leak, bounded cache with no leak, burst allocator with no leak).

Code and installation commands remain unchanged in the original text.