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.

 /leak-scan                          /leak-deep
     |                                   |
     v                                   v
  3x class histogram               (all of scan, plus)
  + GC pressure snapshot            JFR recording
     |                              heap dump
     v                              MAT leak suspects
  monotonic growth?                 async-profiler alloc profile
  old-gen pressure?                     |
     |                                  v
     +--- both true? -----> auto-escalate to deep
     |
     +--- otherwise ------> verdict + next steps

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

git clone https://github.com/your-org/heap-seance.git

2. Add `.mcp.json` to your Java project

In the project you want to investigate, create a .mcp.json:

{
  "mcpServers": {
    "heap-seance": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/heap-seance", "python", "-m", "heap_seance_mcp.server"],
      "env": {
        "JAVA_HOME": "/path/to/jdk-17",
        "MAT_BIN": "/path/to/ParseHeapDump.sh",
        "ASYNC_PROFILER_BIN": "/path/to/asprof"
      }
    }
  }
}

--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:

cp -r /path/to/heap-seance/.claude/commands/ .claude/commands/

4. Run

/leak-scan my-service        # conservative scan
/leak-deep 12345             # full forensics by PID

Heap Seance resolves the target process, collects evidence, and returns a structured verdict.

MCP Tools

Every tool returns the same unified schema:

{
  "status": "ok | warn | error",
  "evidence": ["..."],
  "metrics": {},
  "confidence": "none | low | medium | high",
  "next_recommended_action": "...",
  "raw_artifact_path": "..."
}

Investigation Workflow

1. Start your app and let it initialize fully.
2. /leak-scan <name-or-pid> — takes the first histogram snapshot.
3. Exercise the suspect behavior — the scan prompts you between each of