SuperGhidra: Compilable C Rewriter & Guardrailed Agent MCP Suite.

Python tools that make Ghidra faster to script against, rewrite raw decompiler output into compilable C, and run static binary analyses Ghidra does not include out of the box: MSVC RTTI and MFC CRuntimeClass recovery, Serialize() archive layout tracing, cross-version function and struct-shift matching, and a Z3 equivalence checker for P-code.

Instead of paying 5–15 seconds of JVM startup per headless run or fighting .rep project lock contention while the Ghidra GUI is open, SuperGhidra keeps a single read-only Ghidra instance warm in a background daemon (127.0.0.1:5073) backed by an L2 SQLite cache and a non-destructive JSON write overlay. Heavy binary sweeps and class-layout recovery run in pure Python, NumPy SIMD, or WGPU compute shaders without touching the JVM.

No Ghidra needed, just Python. Recover MSVC RTTI classes and MFC Serialize() layouts straight from a PE file:

pip install superghidra
superghidra rtti-recover target.dll -o classes.json
python -m superghidra.formats.serialize_trace target.dll CMyDoc

Want an AI agent (Claude Desktop, Claude Code, Cursor, Antigravity) driving Ghidra without GUI lockups? Install the MCP server and point it at your project; see Agent & MCP Configuration for the config block. GHIDRA_INSTALL_DIR and JAVA_HOME must be set (Ghidra 11/12 + OpenJDK 21):

pip install git+https://github.com/yuatemycat/SuperGhidraMCP.git
claude mcp add superghidra -- superghidra-mcp -t stdio --project-path <path_to_gpr_or_binary>

SuperGhidra spans four distinct execution paths. Pick the entry point that matches your task before running commands:

python ghidra_oracle.py decompile <addr>

Most Ghidra automation scripts and MCP servers either pay a 5–15 second JVM cold-start penalty per invocation or bind directly to a single mutable GUI session where concurrent agent edits can corrupt the .rep database or trigger LockException. SuperGhidra separates read-only oracle queries (127.0.0.1:5073) from non-destructive overlay writes (ghidra_overlay.json), while executing bulk binary sweeps and C++/MFC recovery in pure Python, NumPy SIMD, and WGPU without touching the JVM.

Ghidra locks .rep projects exclusively, meaning standard headless scripts fail whenever the project is open in the Ghidra GUI. SuperGhidra avoids lock contention by separating reads (served from a warm daemon or read-only session) from writes (recorded in a JSON overlay and transaction journal):

Recover MSVC RTTI hierarchies, MFC CRuntimeClass descriptors, and virtual function tables directly from raw PE binaries without requiring Ghidra or a JVM:

# Direct module execution
python -m superghidra.formats.msvc_class_recovery target.dll

# Or recover classes and export to JSON via unified CLI
superghidra rtti-recover target.dll -o classes.json

# Trace MFC Serialize() archive field layouts
python -m superghidra.formats.serialize_trace target.dll CMyDoc

Point SuperGhidra to NSA Ghidra (11.x or 12.x) and OpenJDK 21:

# Linux / macOS
export GHIDRA_INSTALL_DIR="/opt/ghidra"
export JAVA_HOME="/usr/lib/jvm/java-21-openjdk"

# Windows (PowerShell)
$env:GHIDRA_INSTALL_DIR = "C:\tools\ghidra"
$env:JAVA_HOME = "C:\Program Files\Eclipse Adoptium\jdk-21"

Verify the daemon status or launch it with project coordinates:

# Check daemon status (auto-reports uptime, cache hit rate, and loaded binary)
python ghidra_oracle.py status

# Run daemon with explicit project paths
python ghidra_oracle.py --project-dir ~/re/proj --project-name game --program-name libgame.so status

# Or launch as a dedicated background server on port 5073
python ghidra_oracle.py serve --project-dir ~/re/proj --project-name game --program-name libgame.so --mode balanced

You can also define candidate projects globally via SUPERGHIDRA_PROJECTS="dir,name[,program]".

Subsequent queries execute in < 0.01 ms when served from the SQLite L2 cache:

# Decompile target function by virtual address
python ghidra_oracle.py decompile 0x140001000

# Propose function rename (committed safely to the JSON write overlay)
python ghidra_oracle.py rename 0x140001000 ProcessPacketHeader

# Add an address comment
python ghidra_oracle.py comment 0x140001000 "Validated packet parser entry point"

Mutations are recorded in ghidra_overlay.json to prevent .rep lock collisions. Sync them back into the Ghidra GUI session:

• Option 1 — Live Ghidra GUI Sync (ghidra_gui_overlay_sync.py):

  1. Generate a one-shot sync script or a live background watcher (--watch):

     # One-shot atomic transaction script
     superghidra overlay-sync --overlay ghidra_overlay.json --out ghidra_gui_overlay_sync.py
     
     # Or generate a continuous background watcher script (polls every 1000 ms)
     superghidra overlay-sync --overlay ghidra_overlay.json --watch --poll-ms 1000 --out ghidra_gui_overlay_sync.py

  2. In Ghidra's CodeBrowser, navigate to Window → Script Manager.
  3. Add the output directory to Script Paths and run ghidra_gui_overlay_sync.py. All renames, comments, and type definitions apply atomically inside your active GUI session.

• Option 2 — Headless Journal Replay & Auto-Discard (merge_fork): Close the project in the Ghidra GUI to release the .rep lock, then replay the journal or merge session forks using merge_fork(fork_id, auto_discard=True). When auto_discard=True, once all operations merge cleanly with zero pending conflicts (pending_ops == 0), SuperGhidra automatically deletes the fork's isolated directory and transaction journal to reclaim disk storage. Unneeded or stale forks can also be deleted directly via discard_fork(fork_id).

SuperGhidra exposes 38 specialized reverse-engineering tools via the Model Context Protocol (MCP) using SuperghidraMCP (including recover_cpp_classes, trace_serialize, diff_binaries, verify_smt_equivalence, and gpu_adrp_scan). This enables AI coding agents to inspect binaries, query call graphs, and propose validated renames autonomously.

Install the MCP server from source:

pip install git+https://github.com/yuatemycat/SuperGhidraMCP.git

{
  "mcpServers": {
    "superghidra": {
      "command": "superghidra-mcp",
      "args": [
        "-t",
        "stdio",
        "--project-path",
        "<path_to_gpr_or_binary>"
      ],
      "env": {
        "GHIDRA_INSTALL_DIR": "/opt/ghidra",
        "JAVA_HOME": "/path/to/jdk-21"
      }
    }
  }
}

Alternative using uvx: Replace "command": "superghidra-mcp" with "command": "uvx" and set "args" to:

["--from", "git+https://github.com/yuatemycat/SuperGhidraMCP.git", "superghidra-mcp", "-t", "stdio", "--project-path", "<path_to_gpr_or_binary>"]

Both Cursor and Antigravity use standard JSON mcpServers configuration:

{
  "mcpServers": {
    "superghidra": {
      "command": "superghidra-mcp",
      "args": [
        "-t",
        "stdio",
        "--project-path",
        "<path_to_gpr_or_binary>"
      ],
      "env": {
        "GHIDRA_INSTALL_DIR": "/opt/ghidra",
        "JAVA_HOME": "/path/to/jdk-21"
      }
    }
  }
}

If running the server via HTTP (superghidra-mcp --transport streamable-http --port 8000):

• Claude Code CLI:

  claude mcp add --transport http superghidra http://127.0.0.1:8000/mcp

• HTTP URL Config (Antigravity / Cursor / Claude Desktop):

  {
    "mcpServers": {
      "superghidra": {
        "url": "http://127.0.0.1:8000/mcp"
      }
    }
  }

These subsystems form the daily-driver reverse-engineering, C rewriting, and agent-guardrail workflow:

These modules target specific scale bottlenecks or standalone verification tasks and have explicit scope boundaries:

Each package has its own README under src/superghidra/.

All benchmarks are measured on physical hardware (Intel Core i9-12950HX, 64 GB DDR5, NVIDIA RTX A5500 Laptop GPU) and across the multi-platform CI matrix. Full empirical data and logs are in docs/benchmarks/.

Benchmark Caveats:

• CPU SIMD vs. WGPU Crossover: Below ~5–10 MB, NumPy CPU SIMD (143.95 M insn/s on 4 MB blocks) outperforms WGPU DirectX 12 (127.25 M insn/s on 20 MB blocks) because PCIe host-to-device transfer overhead exceeds shader execution time. gpu_adrp_scanner automatically routes < 5 MB inputs to the CPU SIMD path.
• Synthetic Storage Pages: The 16 KB BufferFile compression figures (442.9 MB/s LZ4, 206.5 MB/s Zstd) are measured on 1,000 synthetic pages generated by GhidraPageSimulator, not on live .rep .gbf databases (Ghidra hardcodes LocalManagedBufferFile without an SPI hook).

Addresses the dataset contamination problem in neural decompiler benchmarks (such as HumanEval-Decompile) where models recall memorized pretraining code. Evaluated under MSVC 14.44 cl.exe / MinGW GCC 16.2.0 via differential co-execution:

• Finding: Raw LLM predictions achieved a 100% compilation rate but a 0.0% semantic pass rate due to subtle binary logic hallucinations. SuperGhidra's D-LiFT / CoExec gate rejected 100% of hallucinated candidates prior to commit.

• Dataset: LLM4Binary/decompile-eval@b9271fae3c556e46948559f4176ffa6f8b4f9491 (1300 evaluable functions from binaries compiled at O0–O3).
• Compiler & Host: Evaluated on Windows AMD64 by recompiling recovered C/C++ with gcc.EXE (MinGW-W64 x86_64-ucrt-posix-seh, built by Brecht Sanders, r3) 16.2.0 under gcc -O0 -lm.
• Host ABI Note: Single-host evaluation. Linux ELF binaries recompiled on Windows (LLP64) experience 32-bit long truncation on raw Ghidra emissions (8.23%). On Linux (LP64), raw Ghidra achieves 21.46% (279/1300), exceeding raw IDA.
• Methodology & Scope Caveat: Measures syntactic recompilability (gcc -O0 -lm) + unit test pass rate via deterministic AST/token rewriting (CompilableDecompilerFilter + defs.h compatibility macros), not neural LLM weight generation.
• 70/30 Held-Out Split: Splitting by unique function body (seed 42, all O0–O3 variants of a function kept together) confirms out-of-sample generalization on the held-out 30% test split (43/388 -> 98/388, +55 gains) with zero regressions.

HumanEval-Decompile Caveat (Deterministic C Rewriter, Not Neural Inference): The 22.62% (294/1,300 full corpus, plus 25.26% on the 30% function-disjoint held-out test split) score measures syntactic recompilability and unit-test execution pass rate produced by CompilableDecompilerFilter — a deterministic post-processing rewriter that strips stack-canary boilerplate, normalizes Ghidra pseudo-types (undefined8, CONCAT44, SUB84), and injects symmetric Hex-Rays defs.h compatibility macros (__int64, LODWORD, HIDWORD, BYTEn) for IDA Pro baselines. No neural model weights or LLM calls are invoked in this benchmark.

Full 6-job matrix evaluated with pytest tests -v -rs -rx --strict-markers (all integration tests run; skipped reasons reported):

Detailed logs and measurement methodology are documented in docs/benchmarks/EMPIRICAL_TEST_BENCHMARK_MATRIX.md.

From PyPI:

pip install superghidra

Optional acceleration and integration extras:

pip install "superghidra[all]"       # all optional backends
pip install "superghidra[smt]"       # Z3 P-code equivalence checker
pip install "superghidra[gpu]"       # WGPU compute shaders (ADRP/prologue sweeps)
pip install "superghidra[storage]"   # LZ4 & Zstandard 16 KB page compression
pip install "superghidra[ghidra]"    # PyGhidra bridge & JVM headless bindings
pip install "superghidra[frida]"     # Live emulator runtime inspection

From source (development):

git clone https://github.com/yuatemycat/SuperGhidra
cd SuperGhidra
pip install -e ".[all]"
python -m pytest -q

Unified CLI:

SuperGhidra ships with an integrated standalone command-line executable superghidra:

# Display version and hardware acceleration telemetry
superghidra version

# Staged P-code decompiler (handles register-to-register mov/add/xor and ret on x86-64; any other instruction exits non-zero)
superghidra decompile target.dll --va 0x140001000 --arch x86_64 -o decompiled.c

# Import IDA Pro .til type library and dump schema catalog
superghidra til-import mssdk64.til -o catalog.json

# Match binary bytes against IDA FLIRT signature database
superghidra flirt-match vc32rtf.sig target.exe --rva 0x1000

# Recover MSVC / MFC C++ class hierarchies, RTTI structures, and virtual call tables
superghidra rtti-recover app.dll -o classes.json

# Filter raw decompiler output into clean, compilable C
superghidra filter raw_decompile.c -o clean.c

# Sync JSON write overlays and delta logs into an atomic Ghidra GUI Python script (add --watch for live polling)
superghidra overlay-sync --overlay ghidra_overlay.json --watch --out sync_script.py

Inspect a Windows binary (no Ghidra needed):

python -m superghidra.formats.binary_loader app.dll          # sections, imports, exports
python -m superghidra.formats.msvc_class_recovery app.dll    # RTTI + MFC classes
python -m superghidra.formats.serialize_trace app.dll CMyDoc # Serialize() field layout

From Python:

from superghidra.formats.binary_loader import load_binary
from superghidra.formats.msvc_class_recovery import recover_classes
import superghidra as sg

img = load_binary("app.dll")
print(img.format, img.arch, len(img.sections))

report = recover_classes("app.dll")
print(len(report.mfc_classes), "MFC classes")

# Lift one ARM64 instruction and check it against itself with Z3
ops = sg.ARM64PcodeLifter().lift_instruction(0x1000, 0x91008041)  # add x1, x2, #0x20
print(sg.SMTPcodeVerifier().verify_equivalence(ops, ops).equivalent)

Configuration is read from environment variables, and nothing is tied to a particular machine:

• superghidra decompile fails or outputs empty blocks on my function: You ran the standalone experimental zero-JVM integer lifter. Switch to python ghidra_oracle.py decompile <addr>.
• LockException: Project is locked by another process: Your .rep project is currently open in the Ghidra GUI. The daemon reads from the project without acquiring exclusive locks; if Ghidra holds an exclusive lock or you encounter lock contention, ensure the daemon uses a read-only session or private session fork, and sync changes back via superghidra overlay-sync --overlay ghidra_overlay.json --out ghidra_gui_overlay_sync.py.
• My renamed functions in the daemon don't show up in the Ghidra GUI: Daemon writes go to the JSON overlay (ghidra_overlay.json) to prevent .rep corruption. Run superghidra overlay-sync --overlay ghidra_overlay.json --out ghidra_gui_overlay_sync.py (or pass --watch for continuous background polling) and execute that script inside Ghidra's Script Manager, or close the GUI and run merge_fork.
• Z3 Equivalence Checker returns UNKNOWN: This is expected behavior, not a crash. The prover returns UNKNOWN whenever a block contains floating-point instructions, unmodeled system instructions, or long loops so an agent never commits a false-positive equivalence rewrite.
• WGPU scanner says Using CPU SIMD path even with [gpu] installed: For ARM64 .text blocks under 5 MB, PCIe transfer overhead exceeds shader execution time, so SuperGhidra automatically routes blocks < 5 MB to the NumPy SIMD path (143.95 M insn/s).
• Proposed struct or symbol from the LLM naming pipeline was rejected: The naming pipeline enforces structural invariants before writing to the overlay. Check the daemon log for VtableSlotMismatch, FieldOffsetOutOfBounds, or AllocationSizeConflict.

• Objective-C Runtime Recovery: Currently recovers classes, methods, and ivars from traditional 64-bit Mach-O binaries with direct pointers (__objc_classlist, __objc_const). Binaries using modern macOS / iOS dyld chained fixups (LC_DYLD_CHAINED_FIXUPS) are not yet dereferenced and are planned for 1.x.
• C++ RTTI Formats: Class recovery targets MSVC RTTI (CompleteObjectLocator, TypeDescriptor, ClassHierarchyDescriptor) and MFC CRuntimeClass. GNU Itanium ABI C++ RTTI (type_info, _vptr prefix structures) is planned for 1.x.
• MFC Class Recovery Testing: Precision and recall (100% precision, 0 false positives on non-MFC binaries such as libcrypto-3.dll) are verified in automated CI using synthetic redistributable PE fixtures (sample_mfc_x64.dll). Real commercial applications (such as WinMerge with 713 RTTI and 160 MFC classes) are evaluated manually.
• MCP Server Package: The Model Context Protocol server is distributed as superghidra-mcp on PyPI (source in SuperghidraMCP), depending on superghidra>=0.4.0 and connecting AI coding agents directly to the local daemon and standalone recovery tools.
• PDB Export: PDB export is experimental: it emits MSF 7.0 structures with prototype DBI and public symbol records, but lacks MSVC-compatible hash streams, symbol record streams, and CodeView type (TPI) streams. DWARF 5 export is the supported path for external tooling.
• SMT Verification Incompleteness: The SMT checker is sound but incomplete. Floats, calls, unhandled ops and long loops return UNKNOWN by design to prevent false equivalence.
• ARM64 Lifter Instruction Surface: The ARM64 lifter covers core integer, exclusive memory, SIMD vector math/bitwise, bitfield moves, conditional selection, and ARMv8.1-A atomics. Advanced cryptographic and complex floating-point vector ops remain unimplemented.
• Java Codec Buffer Hook: The Java codec operates on external .sgdb files or requires patching Ghidra's core jar because Ghidra hardcodes LocalManagedBufferFile with no storage plugin hook.

More detail is in PLAN.md.

src/superghidra/             canonical package, split into 7 domain subsystems
src/superghidra/compat/      backward-compatibility namespace shims
tests/                       domain-isolated pytest suites (790+ tests)
benchmarks/                  reproducible benchmark harnesses and measurement scripts
docs/                        benchmark specifications, walkthroughs, and architecture docs
ghidra_extension_skeleton/   Java BufferFile compression extension
templates/                   scaffolds for modules, MCP tools, and test suites

If you're an AI agent, start with AGENTS.md.

If you find SuperGhidra useful, crypto donations (fast & permissionless) are welcome:

USDT (BEP20 / BNB Smart Chain):

0xd08d47bde441888166b801616754c667672cd502

Issues and PRs are welcome. See CONTRIBUTING.md for the test workflow and the safety rules: read-only projects, verified symbol commits and the emulator allow-list. Report security issues as described in SECURITY.md.

SuperGhidra is licensed under the GNU AGPL-3.0-or-later. If you modify it and let other people use it over a network, for example as a hosted MCP server, you have to offer them your modified source.

If the AGPL doesn't fit your use, a commercial license is available. See COMMERCIAL-LICENSE.md.

Releases up to and including 0.2.0, and commits before the license change, were published under Apache-2.0. Those versions stay under Apache-2.0 and the text is kept in LICENSES/Apache-2.0.txt.

© 2026 yuatemycat and contributors.