pi-ghidra

Autonomous, native Ghidra tools for Pi. No GUI, bridge server, open Ghidra window, or manual project setup is required.

pi-ghidra invokes Ghidra's official analyzeHeadless launcher, imports and analyzes a binary on first use, and reuses a SHA-256-keyed project on later calls. Related operations can be batched into one JVM invocation.

Requirements

• Pi
• Ghidra 12.x
• JDK 21 or newer
• Node.js 20+

Install

pi install npm:pi-ghidra

From Git:

pi install git:github.com/immutex/pi-ghidra

Try a local checkout:

pi -e ./pi-ghidra

Setup

No environment variables or manual config file are normally needed. On first use, pi-ghidra searches common Windows, macOS, and Linux install locations.

If Ghidra is not found, run:

/ghidra-setup

Select a detected installation, enter a directory, or pass it directly:

/ghidra-setup C:\ghidra_12.1.2

You can also tell Pi: “My Ghidra is at C:\ghidra_12.1.2.” Pi will validate and save it. In print or JSON mode, provide the path through the setup tool action instead of using the interactive command.

Saved settings live in ~/.pi/agent/pi-ghidra.json, or PI_CODING_AGENT_DIR/pi-ghidra.json when that variable is set. The setup action can also persist optional javaHome and cacheDir values.

Ghidra location precedence is:

1. Per-call ghidraHome
2. PI_GHIDRA_HOME
3. GHIDRA_HOME
4. Saved setup
5. Automatic discovery

A working JAVA_HOME takes precedence over a saved JDK. On Windows, common Eclipse Adoptium and Oracle JDK locations are also detected. If no JDK home is selected, Ghidra can use Java from PATH.

Use discover to list detected installations and health to show the active Ghidra, JDK, cache, and saved settings.

Usage

Ask Pi to analyze a binary normally. The package exposes one ghidra tool and a skill that teaches Pi the efficient workflow.

Example tool input:

{
  "action": "batch",
  "binary": "./sample.exe",
  "operations": [
    { "action": "info" },
    { "action": "functions", "query": "main", "limit": 20 },
    { "action": "strings", "query": "password", "limit": 50 },
    { "action": "imports", "limit": 100 }
  ]
}

Then decompile an exact function:

{
  "action": "decompile",
  "binary": "./sample.exe",
  "address": "140001000"
}

Actions

| Action | Purpose | | --- | --- | | discover | Find installed Ghidra 12 locations | | setup | Validate and persist Ghidra, JDK, and cache locations | | health | Show detected Ghidra, Java, cache, and capabilities | | analyze, info | Import/analyze as needed and return program metadata | | rebuild | Delete the cached project and analyze from a clean import | | functions, function | List or inspect functions, parameters, locals, and signatures | | decompile | Produce Ghidra decompiler C output | | disassemble, data | Read instructions and defined data | | strings, symbols | Search analyzer-defined strings and symbols | | imports, exports, entry_points | Inspect linkage and entry points | | references, call_graph | Inspect xrefs, callers, and callees | | memory_blocks, memory | Inspect memory layout and read bytes | | search_bytes, search_text | Search wildcard byte patterns or raw UTF-8 text | | analysis_options, set_analysis_options, reanalyze | Inspect/configure analyzers and run fresh analysis passes | | rename, comment, patch | Persist edits in the cached Ghidra project | | batch | Run up to 50 operations in one Ghidra process |

List results accept offset and limit; the maximum page is 2,000 items. Memory reads and patches are capped at 1 MiB. Tool output is capped at 50 KB and the full JSON is saved to a temporary file when truncated.

Cache

Projects are content-addressed by the input binary's SHA-256 and serialized per artifact. Defaults:

• Windows: %LOCALAPPDATA%\pi-ghidra
• macOS: ~/Library/Caches/pi-ghidra
• Linux: ~/pi-ghidra-cache

Override per call with cacheDir, persist a cache directory through the setup action, or set PI_GHIDRA_CACHE. Ghidra rejects project paths containing dot-prefixed directory components, so avoid paths such as ~/.cache/pi-ghidra.

Edits affect only the cached Ghidra project. The source binary is copied and never modified.

Development

npm install
npm run check
npm test
npm run pack:check

Run the real-Ghidra integration suite:

GHIDRA_HOME=/path/to/ghidra \
GHIDRA_TEST_BINARY=/path/to/test-binary \
npm run test:integration

PowerShell:

$env:GHIDRA_HOME = "C:\ghidra_12.1.2"
$env:GHIDRA_TEST_BINARY = "C:\Windows\System32\where.exe"
npm run test:integration

Security

Ghidra parses untrusted binaries with native components. This package provides process isolation and bounded output, not an OS sandbox. Analyze hostile files in a disposable VM or container. The package deliberately does not expose arbitrary Java/Python execution or network transport.

License

MIT. Ghidra is a separate Apache-2.0-licensed project and is not bundled.