binharness

A reverse-engineering toolkit for stripped Nintendo Switch modules (and any binary), packaged three ways:

• Codex plugin (hex-viewer): an interactive hex viewer that renders inline in Codex (for when the file pane says "Binary file previews aren't supported yet"), plus 24 RE tools Codex can call.

• MCP server: the same tools for any MCP client (npx -y binharness binharness-mcp).

• deepseek-bin: a DeepSeek CLI agent that drives the tools to reverse a module on its own.

• deepseek-bin: a standalone CLI agent that uses the same tools with DeepSeek models.

What it can do

Hand-off to Ghidra/IDA. extract_image main out.bin writes the decompressed image; export_symbols main --out out writes out.ghidra.py / out.ida.py. Load out.bin as a flat AArch64 binary at base 0x7100000000, run the script, and every recovered function, vtable, syscall wrapper and service label is applied.

Stripped Switch sysmodules (no symbol table, statically-linked SDK) are the main target: list_functions reconstructs the function layout, scan_syscalls shows the kernel interface, and find_string_refs gets you from an error message to the code. extract_image hands the rest off to Ghidra/IDA.

Formats. Switch: NSO (LZ4 segments), NRO, NSP/PFS0, XCI/HFS0, NPDM, SARC, BNTX, BFRES, BFSTM, MSBT, BYML, AAMP. Also ELF, Mach-O, PE, PNG/JPEG/GIF, ZIP/gzip/7z/zstd, SQLite, wasm, GameCube/Wii (DOL, REL, Yaz0, RARC, disc images). NSO/NRO addresses use base 0x7100000000 by default (override with base).

NCA files are encrypted. This toolkit does not decrypt them or handle console keys, so give it NSO/NRO files you've already extracted (for example exefs/main).

Related MCP server: Jukeyman Unleashed

Codex plugin

codex plugin marketplace add dougchansan/binharness
codex plugin add hex-viewer@dougchansan

Restart Codex, then try "Show exefs/main in the hex viewer" or "Find the function that prints the save-data error in main.nso".

deepseek-bin (DeepSeek CLI agent)

git clone https://github.com/dougchansan/binharness && cd binharness
export DEEPSEEK_API_KEY=sk-...        # https://platform.deepseek.com
node harness/deepseek-bin.mjs exefs/main

Interactive session with streaming output, tool-call trace and a running cost line. One-shot mode:

node harness/deepseek-bin.mjs -p "Find where the game loads its save file and reconstruct that function in C" exefs/main

Recon. On a stripped module, run the naming passes up front so the agent starts from a named module instead of raw sub_…:

node harness/deepseek-bin.mjs --recon -p "what does this module do?" exefs/main

--recon (or /recon <file> in the REPL) runs parse_npdm, label_rtti, label_syscalls and label_services directly — no model tokens — then hands the agent the summary. RTTI alone typically names hundreds to >1000 functions, and the labels persist, so later sessions start oriented too.

REPL commands: /model, /effort, /add <file>, /files, /cost, /save notes.md, /reset, /exit. Ctrl-C interrupts the current turn.

Why it's cheap: the conversation is append-only, so DeepSeek's prompt cache covers almost every request (cache hits cost ~2% of misses). Tool outputs are capped, and the agent is told to make small, targeted calls. Annotations persist, so the next session starts from what earlier ones learned instead of re-deriving it. Session transcripts are written to ~/.binharness/sessions/.

Using the tools from other agents

The MCP server works with any MCP client. For opencode with DeepSeek:

{
  "model": "deepseek/deepseek-flash",
  "mcp": {
    "binharness": { "type": "local", "command": ["node", "/path/to/binharness/plugins/hex-viewer/server.mjs"] }
  }
}

Layout

.agents/plugins/marketplace.json     Codex marketplace "dougchansan"
plugins/hex-viewer/
  .codex-plugin/plugin.json          plugin manifest
  .mcp.json, server.mjs              stdio MCP server + view_binary UI wiring
  lib/bintools.mjs                   the toolkit (formats, LZ4, AArch64 xrefs, objdump wrapper)
  assets/app.html                    hex viewer UI (MCP App)
  skills/hex-viewer/SKILL.md         tells Codex when/how to use the tools
harness/deepseek-bin.mjs             DeepSeek agent
tests/                               synthetic NSO fixture, mock DeepSeek API, test suite

Requires Node 18+ and objdump (bundled with macOS Command Line Tools; on Linux install llvm for llvm-objdump and symlink or alias it as objdump). No npm dependencies. Run npm test to check your setup.

License

MIT