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.