/ghidra-rpc

name: ghidra-rpc
description: >
  Reverse engineering assistant powered by Ghidra. Use for binary analysis,
  decompilation, vulnerability research, auditing compiled code, renaming symbols,
  annotating disassembly, cross-references, or any RE task - even without explicit
  mention of Ghidra.

Ghidra RPC

A CLI daemon that exposes Ghidra reverse engineering capabilities over a Unix domain socket. You interact with it by running `ghidra-rpc` commands via the bash tool - every command outputs JSON to stdout.

Running Commands

**All `ghidra-rpc` commands must be run with `uv run` from the ghidra-rpc skill directory (the directory containing this SKILL.md file):**

cd <skill-dir> && uv run ghidra-rpc <command> ...

Prerequisites Check

Before using any commands, verify the setup:

1. **Is the daemon running?** Run `uv run ghidra-rpc status --project <path>`. If not running, the user needs to start it in a separate terminal: `uv run ghidra-rpc start --project /path/to/project.gpr` (blocking, human-only). The `--headless` flag skips the GUI. For non-blocking / automated startup use `start --detach --headless` or `restart --headless`. Both commands accept `--timeout SECS` (default: 60 s headless, 180 s GUI) and log daemon output to `/tmp/ghidra-rpc-<hash>.log` (`%LOCALAPPDATA%\ghidra-rpc\ghidra-rpc-<hash>.log` on Windows). 2. **GUI mode: verify the correct project is active.** The daemon passes the `--project` path directly to GhidraRun so Ghidra opens the requested project immediately. After `start --detach` (GUI mode), confirm the right project is loaded before issuing any analysis commands:

   uv run ghidra-rpc list-project-programs --project /path/to/project.gpr

Cross-check the returned binary names against what you expect. If the names don't match (or a `warning` field appears in the response), stop and ask the user to open the correct project in Ghidra's Project window before proceeding. 3. **GUI mode: open the binary in CodeBrowser.** In GUI mode the daemon discovers programs via the running CodeBrowser tool. If the binary is in the project but not currently open in CodeBrowser, `list-binaries` will return empty and all commands will fail with "Binary not found". Use `list-project-programs` to see what's stored in the project, then double-click the program in Ghidra's Project window to open it. 4. **Is `GHIDRA_INSTALL_DIR` set?** The daemon will fail loudly if this is missing.

Once the daemon is running, all commands below work automatically. If the daemon dies, commands will attempt auto-restart from the saved session.

Command Reference

Every command accepts `--project <path>` (or reads `GHIDRA_RPC_PROJECT` env var). All output is JSON. Exit code 0 = success, 1 = error.

Project Management

| Command | Description | Example | |---------|-------------|---------| | `ghidra-rpc start --project <gpr> [--headless] [--detach] [--ghidra-install-dir DIR]` | Start daemon (blocking by default; `--detach` backgrounds it) | `ghidra-rpc start -p /tmp/re.gpr --headless --detach` | | `ghidra-rpc stop --project <gpr>` | Stop the daemon | `ghidra-rpc stop -p /tmp/re.gpr` | | `ghidra-rpc status --project <gpr>` | Check if daemon is running | `ghidra-rpc status -p /tmp/re.gpr` |

`status` output: `{running, socket, mode, mode_source, project, binaries}`. `binaries` is the loaded-binary list when the daemon is running, `null` when stopped (one-shot health check without a second `list-binaries` call). `mode_source` is `"running"` when the daemon is live, `"session"` when the mode is from the saved session only (daemon stopped), and `null` if no session exists. | `ghidra-rpc restart --project <gpr> [--headless] [--timeout SECS] [--ghidra-install-dir DIR]` | Restart daemon in background (`--headless` to override mode) | `ghidra-rpc restart -p /tmp/re.gpr --headless` | | `ghidra-rpc list-binaries --project <gpr>` | List binaries loaded in daemon | `ghidra-rpc list-binaries -p /tmp/re.gpr` | | `ghidra-rpc list-project-programs --project <gpr>` | List all programs stored in the project repo (reads project folder, not CodeBrowser live state; returns `warning` if the active Ghidra project doesn't match) | `ghidra-rpc list-project-programs -p /tmp/re.gpr` | | `ghidra-rpc save [binary] --project <gpr>` | Save program(s) to disk (auto-save also runs after every write) | `ghidra-rpc save -p /tmp/re.gpr` |

Loading & Analysis

| Command | Description | Example | |---------|-------------|---------| | `ghidra-rpc load <path> -p <gpr> [--no-analyze] [--analysis-timeout SECS]` | Import & analyze a binary | `ghidra-rpc load /usr/bin/target -p /tmp/re.gpr` | | `ghidra-rpc metadata <binary> -p <gpr>` | Binary metadata (arch, bits, format) | `ghidra-rpc metadata target -p /tmp/re.gpr` |

`load` flags:

• `--no-analyze` - skip auto-analysis entirely (fast; useful when you only need the

listing or plan to run analysis later via Ghidra GUI).

• `--analysis-timeout SECS` - abort auto-analysis after the given wall-clock budget

(best-effort); the binary is saved with whatever analysis completed in time.

Listing

| Command | Description | Output shape | |---------|-------------|--------------| | `ghidra-rpc functions <binary> [--offset N] [--limit N] [--address-min ADDR] [--address-max ADDR] [--with-body]` | List functions (paginated); `--address-min/max` for server-side range filter; `--with-body` adds body range fields | `{functions: [{name, address, signature[, body_min, body_max, body_size]}], count, total, offset}` | | `ghidra-rpc imports <binary>` | List imports | `{imports: [{name, address, library}], count}` | | `ghidra-rpc exports <binary>` | List exports | `{exports: [{name, address}], count}` | | `ghidra-rpc relocations <binary> [--address ADDR] [--limit N]` | List relocation table entries | `{relocations: [{address, type, symbol, bytes, status}], count, total}` | | `ghidra-rpc list-calling-conventions <binar