{"_id":"pi-ghidra","_rev":"2-adc2709cd505a99f62b152842d46100a","name":"pi-ghidra","dist-tags":{"latest":"0.3.0"},"versions":{"0.2.0":{"name":"pi-ghidra","version":"0.2.0","keywords":["pi-package","ghidra","reverse-engineering","decompiler","headless"],"author":{"name":"immutex"},"license":"MIT","_id":"pi-ghidra@0.2.0","maintainers":[{"name":"immutexx","email":"serpentcontactexp@gmail.com"}],"homepage":"https://github.com/immutex/pi-ghidra#readme","bugs":{"url":"https://github.com/immutex/pi-ghidra/issues"},"pi":{"skills":["./skills"],"extensions":["./extensions/index.ts"]},"dist":{"shasum":"8859cdef40cf2a4d0dd1a682a94154857de2f53b","tarball":"https://registry.npmjs.org/pi-ghidra/-/pi-ghidra-0.2.0.tgz","fileCount":7,"integrity":"sha512-k7LuwmorRLOsXIsQ6XNs7LOHqBxEFq52wxueOk0TYaoBiPvnLsTQY7+RyYE+udBbgRtZOGi/w8FKRZT6o0dyIA==","signatures":[{"sig":"MEQCIFm5T3Vh1sKBJwi4djshqLDstIn3LVoCwGP+3ZNI/AmcAiBG5O7UM85gIUz68ZSwLMg7bnAUMwZkD54kus9D54h+nA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":78818},"type":"module","engines":{"node":">=20"},"gitHead":"e02714b4c091695bec28b1b8b5be1adbc26716ea","scripts":{"test":"tsx --test test/runtime.test.ts test/extension.test.ts","check":"tsc --noEmit","pack:check":"npm pack --dry-run","prepublishOnly":"npm run check && npm test","test:integration":"tsx --test test/integration.test.ts"},"_npmUser":{"name":"immutexx","email":"serpentcontactexp@gmail.com"},"repository":{"url":"git+https://github.com/immutex/pi-ghidra.git","type":"git"},"_npmVersion":"11.16.0","description":"Autonomous headless Ghidra analysis tools for Pi","directories":{},"_nodeVersion":"24.18.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"latest","typebox":"latest","typescript":"latest","@types/node":"latest","@earendil-works/pi-ai":"latest","@earendil-works/pi-coding-agent":"latest"},"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-ghidra_0.2.0_1785256663503_0.13866949316212973","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"pi":{"skills":["./skills"],"extensions":["./extensions/index.ts"]},"_id":"pi-ghidra@0.3.0","omp":{"extensions":["./extensions/index.ts"]},"bugs":{"url":"https://github.com/immutex/pi-ghidra/issues"},"dist":{"shasum":"00e18ecc83afa25ac49bacd26ea52189388af2bf","tarball":"https://registry.npmjs.org/pi-ghidra/-/pi-ghidra-0.3.0.tgz","fileCount":13,"integrity":"sha512-jtrFkxJfXo345wnWPgEoKHJatVI5fGczF27+2cH6GvK7Nz9/c0SFg+HC66RwS0VegzJewn//oom++amxhXjtRw==","signatures":[{"sig":"MEUCICPd6M3zbvN9aARguAqKiH8OJe1TjPi7rlPQ/O80dGjQAiEAzG4XpHeqIL3KCBvp+Kh7usQH8yeOvmcQW5UymOwVg5c=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQClQArY/GmFT/LoGzEX3UoIql5Cjg9COWjVmReoriuNFgIhAI+H4uk+W8yE8uxie2FVSlghPG2TRJ6kFr+2LIFZNXfg"}],"unpackedSize":125065},"name":"pi-ghidra","type":"module","author":{"name":"immutex"},"engines":{"node":">=22.19.0"},"gitHead":"33e7386ef5e4db64d16fb4bf11b1d003a73ee4e9","license":"MIT","scripts":{"test":"tsx --test test/runtime.test.ts test/extension.test.ts test/mcp.test.ts","check":"tsc --noEmit","pack:check":"npm pack --dry-run","prepublishOnly":"npm run check && npm test","test:integration":"tsx --test test/integration.test.ts"},"version":"0.3.0","_npmUser":{"name":"immutexx","email":"immutex@aster.cx"},"homepage":"https://github.com/immutex/pi-ghidra#readme","keywords":["pi-package","pi","omp","oh-my-pi","mcp","mcp-server","ghidra","ghidra-headless","reverse-engineering","binary-analysis","decompiler","disassembler","malware-analysis","firmware","headless","ai-agent","coding-agent"],"repository":{"url":"git+https://github.com/immutex/pi-ghidra.git","type":"git"},"_npmVersion":"11.16.0","description":"Autonomous headless Ghidra 12 reverse engineering for Pi, omp, and MCP clients: decompile, xrefs, call graphs, strings, memory, and patches without the GUI.","directories":{},"maintainers":[{"name":"immutexx","email":"immutex@aster.cx"}],"_nodeVersion":"24.18.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"latest","typebox":"latest","typescript":"latest","@types/node":"latest","@earendil-works/pi-coding-agent":"latest"},"peerDependencies":{"typebox":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-ghidra_0.3.0_1792431306204_0.2366635046855885"}}},"time":{"created":"2026-07-28T16:37:43.349Z","modified":"2026-10-19T17:35:06.475Z","0.2.0":"2026-07-28T16:37:43.633Z","0.3.0":"2026-10-19T17:35:06.305Z"},"bugs":{"url":"https://github.com/immutex/pi-ghidra/issues"},"author":{"name":"immutex"},"license":"MIT","homepage":"https://github.com/immutex/pi-ghidra#readme","keywords":["pi-package","pi","omp","oh-my-pi","mcp","mcp-server","ghidra","ghidra-headless","reverse-engineering","binary-analysis","decompiler","disassembler","malware-analysis","firmware","headless","ai-agent","coding-agent"],"repository":{"url":"git+https://github.com/immutex/pi-ghidra.git","type":"git"},"description":"Autonomous headless Ghidra 12 reverse engineering for Pi, omp, and MCP clients: decompile, xrefs, call graphs, strings, memory, and patches without the GUI.","maintainers":[{"name":"immutexx","email":"immutex@aster.cx"}],"readme":"<h1 align=\"center\">pi-ghidra</h1>\n\n<p align=\"center\">\n  <strong>Autonomous, headless Ghidra 12 for Pi, omp, and any MCP client.</strong><br>\n  Decompile, trace xrefs, map call graphs, search bytes, and patch a program database\n  without opening the GUI, running a bridge server, or preparing a project by hand.\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/immutex/pi-ghidra/actions/workflows/ci.yml\"><img alt=\"CI\" src=\"https://github.com/immutex/pi-ghidra/actions/workflows/ci.yml/badge.svg\"></a>\n  <a href=\"LICENSE\"><img alt=\"License: MIT\" src=\"https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square\"></a>\n  <img alt=\"Node.js 22.19+\" src=\"https://img.shields.io/badge/node-%E2%89%A522.19-339933.svg?style=flat-square&logo=node.js&logoColor=white\">\n  <img alt=\"Ghidra 12\" src=\"https://img.shields.io/badge/Ghidra-12.x-orange.svg?style=flat-square\">\n  <img alt=\"Platforms\" src=\"https://img.shields.io/badge/platforms-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg?style=flat-square\">\n  <img alt=\"MCP\" src=\"https://img.shields.io/badge/MCP-stdio-6f42c1.svg?style=flat-square\">\n  <img alt=\"Agents: Pi and omp\" src=\"https://img.shields.io/badge/agents-Pi%20%7C%20omp-success.svg?style=flat-square\">\n</p>\n\n## What pi-ghidra is\n\n`pi-ghidra` gives a coding agent a real reverse-engineering loop. The agent calls one\n`ghidra` tool; the tool invokes Ghidra's official `analyzeHeadless` launcher, imports\nthe binary on first use, analyzes it, and answers from a cached project on later calls.\nRelated questions run in a single JVM through `batch`.\n\nNothing else is required: no PyGhidra daemon, no Ghidra plugin, no open project, no\nbridge port. The package is a thin TypeScript scheduler around one Java `GhidraScript`\nthat is the entire Ghidra API adapter.\n\n|  | pi-ghidra | GUI automation | Long-lived bridge |\n|---|---|---|---|\n| Setup | Install package; Ghidra auto-detected | Launch and drive a GUI | Run and supervise a server |\n| Isolation | One disposable JVM per call | Shared GUI state | Shared JVM and project state |\n| Cancellation | Process-tree kill | Fragile UI abort | RPC-level only |\n| Failure scope | One call | Whole session | Whole daemon |\n| Cache | SHA-256 content-addressed projects | Manual | Custom |\n| Hosts | Pi, omp, MCP clients | Usually one | Usually one |\n\nThe design trades warm-call latency for crash isolation and predictable cancellation.\nBatch related operations when latency matters.\n\n> [!NOTE]\n> Edits (`rename`, `comment`, `patch`) persist in the cached Ghidra project only.\n> The source binary is copied into the cache and never modified.\n\n\n## Example session\n\n```text\n❯ find the config parser, decompile it, and show what calls it\n\n✓ ghidra  batch  4.2s\n  functions  query=\"config\"        → 6 matches\n  decompile  address=140012a40     → C output + signature\n  call_graph address=140012a40     → 2 callers, 5 callees\n\n❯ what does the caller at 140010f20 pass in?\n\n✓ ghidra  decompile  1.1s\n  ...\n```\n\nThe first call imports and analyzes the binary, so it takes as long as a normal\nheadless Ghidra analysis. Later calls reuse the cached project.\n\n## Quick start\n\n### Pi\n\n```bash\npi install npm:pi-ghidra\n```\n\nFrom Git, or from a checkout:\n\n```bash\npi install git:github.com/immutex/pi-ghidra\npi install ./pi-ghidra\n```\n\n### omp\n\n```bash\nomp plugin install pi-ghidra\n```\n\nRequires pi-ghidra 0.3.0 or newer on npm; that release adds the `omp.extensions`\nmanifest. From a checkout:\n\n```bash\nomp plugin link .\n```\n\nThe package declares both `pi.extensions` and `omp.extensions`, so the same\n`extensions/index.ts` loads under either harness. Skills ship in `skills/` and are\ndiscovered by both.\n\n### MCP (any client)\n\nThe `mcp/server.ts` entry point is a zero-dependency stdio MCP server over the same\nruntime. Run it with Node 22.19+ (native TypeScript stripping):\n\n```bash\nnode /path/to/pi-ghidra/mcp/server.ts\n```\n\nRegister it with an MCP client, for example omp's `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"pi-ghidra\": {\n      \"command\": \"node\",\n      \"args\": [\"C:/path/to/pi-ghidra/mcp/server.ts\"]\n    }\n  }\n}\n```\n\nCommand Code:\n\n```bash\ncmd mcp add-json pi-ghidra '{\"command\":\"node\",\"args\":[\"C:/path/to/pi-ghidra/mcp/server.ts\"]}' -s user\n```\n\nThe server exposes one `ghidra` tool with the same schema as the extension, plus an\noptional `cwd` argument for relative binary paths. It implements `initialize`,\n`tools/list`, `tools/call`, `ping`, and `notifications/cancelled`.\n\n### Requirements\n\n| Component | Version |\n|---|---|\n| Ghidra | 12.x |\n| JDK | 21 or newer |\n| Node.js | 22.19+ (MCP server only; Pi and omp bundle their runtime) |\n| Pi | 1.x, or omp 18.x, or any MCP client |\n\n## Setup\n\nNo environment variables or config file are normally needed. On first use,\n`pi-ghidra` searches common install locations on Windows, macOS, and Linux, including\npackage-manager roots and user folders.\n\nIf Ghidra is not found:\n\n```text\n/ghidra-setup\n```\n\nSelect a detected installation, enter a directory, or pass one directly:\n\n```text\n/ghidra-setup C:\\ghidra_12.1.2\n```\n\nYou can also tell the agent: \"My Ghidra is at `C:\\ghidra_12.1.2`.\" It validates the\npath with `action: \"setup\"` and persists it. In print, JSON, or MCP mode, call the\n`setup` action directly instead of using the interactive command.\n\nSettings live in the active harness agent directory:\n\n| Harness | Default path |\n|---|---|\n| Pi | `~/.pi/agent/pi-ghidra.json` |\n| omp | `~/.omp/agent/pi-ghidra.json` |\n| Either | `PI_CODING_AGENT_DIR/pi-ghidra.json` |\n| Override | `PI_GHIDRA_CONFIG` (full file path) |\n\nGhidra resolution order:\n\n1. Per-call `ghidraHome`\n2. `PI_GHIDRA_HOME`\n3. `GHIDRA_HOME`\n4. Saved setup\n5. Automatic discovery\n\n`JAVA_HOME` wins when it is JDK 21+; otherwise the saved `javaHome`, then common\nJDK locations on Windows, macOS, and Linux. If none is selected, Ghidra uses the\nJava on `PATH`.\n\nUse `discover` to list candidates and `health` to report the active Ghidra, JDK,\ncache, config path, and detected homes. `health` returns `error` and a `null`\n`ghidraHome` when Ghidra is missing instead of failing, which makes it a safe first\ndiagnostic.\n\n## Usage\n\nAsk the agent to analyze a binary. The package exposes one `ghidra` tool and a skill\nthat teaches the efficient workflow.\n\nInventory in one JVM:\n\n```json\n{\n  \"action\": \"batch\",\n  \"binary\": \"./sample.exe\",\n  \"operations\": [\n    { \"action\": \"info\" },\n    { \"action\": \"functions\", \"query\": \"main\", \"limit\": 20 },\n    { \"action\": \"strings\", \"query\": \"password\", \"limit\": 50 },\n    { \"action\": \"imports\", \"limit\": 100 }\n  ]\n}\n```\n\nDecompile an exact function:\n\n```json\n{\n  \"action\": \"decompile\",\n  \"binary\": \"./sample.exe\",\n  \"address\": \"140001000\"\n}\n```\n\nTrace what reaches a function, then inspect its callees:\n\n```json\n{\n  \"action\": \"batch\",\n  \"binary\": \"./sample.exe\",\n  \"operations\": [\n    { \"action\": \"references\", \"address\": \"140001000\", \"direction\": \"to\", \"limit\": 50 },\n    { \"action\": \"call_graph\", \"address\": \"140001000\", \"limit\": 50 }\n  ]\n}\n```\n\n## Actions\n\n| Action | Purpose |\n|---|---|\n| `discover` | Find installed Ghidra 12 locations |\n| `setup` | Validate and persist Ghidra, JDK, and cache locations |\n| `health` | Report Ghidra, Java, cache, config, and detected homes |\n| `analyze`, `info` | Import/analyze as needed and return program metadata |\n| `rebuild` | Delete the cached project and analyze from a clean import |\n| `functions`, `function` | List or inspect functions, parameters, locals, and signatures |\n| `decompile` | Produce Ghidra decompiler C output |\n| `disassemble`, `data` | Read instructions and defined data |\n| `strings`, `symbols` | Search analyzer-defined strings and symbols |\n| `imports`, `exports`, `entry_points` | Inspect linkage and entry points |\n| `references`, `call_graph` | Inspect xrefs, callers, and callees |\n| `memory_blocks`, `memory` | Inspect memory layout and read bytes |\n| `search_bytes`, `search_text` | Search wildcard byte patterns or raw UTF-8 text |\n| `analysis_options`, `set_analysis_options`, `reanalyze` | Inspect/configure analyzers and run fresh analysis passes |\n| `rename`, `comment`, `patch` | Persist edits in the cached Ghidra project |\n| `batch` | Run up to 50 operations in one Ghidra process |\n\nRules enforced before a JVM starts:\n\n- `binary` is required for every operation action, `batch`, and `rebuild`.\n- `decompile`, `function`, `call_graph`, `memory`, `references`, `comment`, `rename`,\n  and `patch` need an `address` or `name`.\n- `search_bytes` needs `pattern`; `search_text` needs `query`.\n- `patch` needs `bytes`; `rename` needs `value`; `set_analysis_options` needs `options`.\n- Unknown fields are rejected so typos fail loudly instead of being ignored.\n\nList results accept `offset` and `limit`; the maximum page is 2,000 items. Memory reads\nand patches are capped at 1 MiB. Byte and text searches scan at most 64 MiB and return\n`{ matches, scannedBytes, truncated }`. Tool output is capped at 50 KB; the extension\nwrites the full JSON to a temporary file when truncated, and MCP clients get a\ntruncation notice.\n\n## Cache\n\nProjects are content-addressed by the input binary's SHA-256 and serialized per\nartifact with a lock file, so concurrent calls cannot corrupt a project.\n\n| Platform | Default cache |\n|---|---|\n| Windows | `%LOCALAPPDATA%\\pi-ghidra` |\n| macOS | `~/Library/Caches/pi-ghidra` |\n| Linux | `~/pi-ghidra-cache` |\n\nOverride per call with `cacheDir`, persist one through `setup`, or set\n`PI_GHIDRA_CACHE`. Ghidra rejects project paths containing dot-prefixed directory\ncomponents, so avoid paths such as `~/.cache/pi-ghidra`. On Windows, paths containing\n`&`, `%`, `!`, `^`, `|`, `<`, `>`, `\"`, `?`, or `*` are also rejected.\n\nAnalysis imports are staged in `project.next` and renamed into place only after a\nsuccessful run, so a crash cannot leave a half-written cache. `PI_GHIDRA_CPUS`\ncontrols `-max-cpu` (default 2, capped at 4).\n\n## Architecture\n\n```text\nextensions/index.ts   Pi/omp tool + /ghidra-setup command\nmcp/server.ts         stdio JSON-RPC 2.0 wrapper (no dependencies)\nsrc/runtime.ts        validation, discovery, cache, locks, process control\nsrc/schema.ts         one JSON Schema shared by every host\nsrc/metadata.ts       tool descriptions shared by every host\nsrc/text.ts           UTF-8-safe output truncation\nghidra_scripts/\n  PiGhidra.java       the only Ghidra-side adapter\nskills/ghidra/\n  SKILL.md            workflow guidance for the agent\n```\n\nOne call follows a fixed path:\n\n```text\ntool call\n  -> validate request\n  -> resolve Ghidra 12 + JDK\n  -> hash binary, acquire per-artifact lock\n  -> import + analyze (staged) or reuse cached project\n  -> analyzeHeadless -process -postScript PiGhidra.java request.json response.json\n  -> validate response JSON\n  -> release lock, return result\n```\n\nGhidra's stdout is treated as diagnostics, never as protocol. Requests and responses\nare files, so quoting and log noise cannot corrupt a result.\n\n## Development\n\n```bash\nnpm install\nnpm run check          # tsc --noEmit\nnpm test               # unit + MCP protocol tests\nnpm run pack:check     # inspect the published file set\n```\n\nRun the real-Ghidra suite:\n\n```bash\nGHIDRA_HOME=/path/to/ghidra \\\nGHIDRA_TEST_BINARY=/path/to/test-binary \\\nnpm run test:integration\n```\n\nPowerShell:\n\n```powershell\n$env:GHIDRA_HOME = \"C:\\ghidra_12.1.2\"\n$env:GHIDRA_TEST_BINARY = \"C:\\Windows\\System32\\where.exe\"\nnpm run test:integration\n```\n\nThe integration suite imports a real binary, batches inventory and decompilation,\napplies a rename/comment/patch, verifies the edit, and restores the original state.\n\nLoad the extension under either harness without installing it:\n\n```bash\npi -e ./pi-ghidra\nomp --no-extensions -e ./extensions/index.ts\n```\n\n## Security\n\nGhidra parses untrusted binaries with native components. This package provides\nprocess isolation, bounded output, and a path allowlist for its own artifacts; it is\nnot an OS sandbox. Analyze hostile files in a disposable VM or container.\n\nThe tool deliberately does not expose arbitrary Java/Python execution, arbitrary\nproject paths, or a network transport. Patch and rename operations affect only the\ncached project. Report vulnerabilities privately through\n[GitHub Security Advisories](https://github.com/immutex/pi-ghidra/security/advisories/new);\nsee [SECURITY.md](SECURITY.md).\n\n\n## FAQ\n\n**Does it modify the binary?**\nNo. The binary is copied into the cache and hashed. `rename`, `comment`, and `patch`\nchange only the cached Ghidra project.\n\n**Can I use it without Pi?**\nYes. omp loads the same extension, and `mcp/server.ts` exposes the same tool to any\nMCP client.\n\n**Does it support Ghidra 11?**\nNo. The adapter uses Ghidra 12 APIs and validates `application.version` against `12.`.\n\n**Why is the first call slow?**\nIt starts a JVM, imports the binary, and runs the analyzers. Use `batch` to amortize\nthe JVM start, and reuse the SHA-256 cache for later calls.\n\n**Can two analyses run at once?**\nDifferent binaries run in parallel. Calls for the same binary are serialized by a lock\nso the project cannot be corrupted.\n\n**Is there a JavaScript API?**\n`src/runtime.ts` exports `runGhidra`, `discoverGhidraHomes`, `resolveGhidraHome`,\n`validateGhidraRequest`, and the action constants. The Pi/omp extension and MCP server\nare thin adapters over it.\n\n**Where do I report a security issue?**\nThrough [GitHub Security Advisories](https://github.com/immutex/pi-ghidra/security/advisories/new),\nnever in a public issue.\n\n## Contributing\n\nRead [CONTRIBUTING.md](CONTRIBUTING.md) for setup, the code layout, and the checks CI\nruns. Every trap that costs real time should end up as a test or a documented\nconstraint.\n\n- [Changelog](CHANGELOG.md)\n- [Code of Conduct](CODE_OF_CONDUCT.md)\n- [Security policy](SECURITY.md)\n\n## License\n\nMIT. Ghidra is a separate Apache-2.0 project and is not bundled.\n\n**Topics:** `ghidra` · `reverse-engineering` · `binary-analysis` · `decompiler` ·\n`disassembler` · `headless` · `mcp` · `mcp-server` · `pi-package` · `pi` · `omp` ·\n`oh-my-pi` · `ai-agent` · `malware-analysis` · `firmware`\n","readmeFilename":"README.md"}