Heap Seance

What is Heap Seance?

Heap Seance is an MCP server and CLI toolkit that integrates jcmd, jmap, jstat, jfr, Eclipse MAT, and async-profiler into a structured Java heap leak investigation workflow. It is designed to run inside Claude Code and provides two slash commands and eight MCP tools for conservative-to-deep leak analysis.

How to use Heap Seance?

Clone the repository, add a .mcp.json configuration to your Java project pointing to the Heap Seance directory, and copy the .claude/commands/ folder into the project. Then invoke the /leak-scan or /leak-deep slash commands from Claude Code, or use the CLI directly via uv run heap-seance --mode scan --match <name> or --mode deep --pid <pid>. The tools require Python 3.10+, JDK 17+, and uv. Deep mode additionally requires Eclipse MAT CLI.

Key features of Heap Seance

• Two‑stage escalation: /leak-scan (conservative) then /leak-deep (full forensics)
• Eight MCP tools: process listing, class histograms, GC snapshots, JFR recording, heap dumps, MAT leak suspects, and async-profiler allocation profiles
• Unified confidence ladder: none → low → medium → high based on independent signals
• Conservative by default: no deep forensics unless evidence demands it
• Automatic artifact saving for team review
• CLI mode available without Claude Code

Use cases of Heap Seance

• Diagnosing Java memory leaks in production or staging environments
• Identifying root holder chains and dominant retainers in heap dumps
• Validating fix effectiveness by re‑scanning after code changes
• Investigating growth patterns combined with GC pressure signals
• Generating structured evidence for team reviews or incident reports

FAQ from Heap Seance

What dependencies are required?

Python 3.10+, JDK 17+ for tooling (jcmd, jmap, jstat), and uv for environment management. Deep mode (/leak-deep) requires Eclipse MAT CLI. async‑profiler is optional.

Can Heap Seance analyze Java 8 target applications?

Yes, histogram, GC, and MAT work fully. JFR is skipped for Java 8 targets due to incompatible file format.

Where does Heap Seance save artifacts?

By default, artifacts (.jfr, .hprof, MAT reports) are saved to the system temporary directory. Override with the HEAP_SEANCE_ARTIFACT_DIR environment variable.

Is async-profiler required for deep mode?

No, async‑profiler is optional. Deep mode works without it, using JFR and MAT for evidence.

What Java version does the target application need?

The target application can run any Java version (including Java 8). The tooling JDK must be 17+.