Documentation Plugin Reference

Everything you need to install, configure, and use Rikugan, the AI reverse-engineering plugin for IDA Pro and Binary Ninja.

Requirements

• IDA Pro 9.0+ with Hex-Rays decompiler (recommended), or Binary Ninja (UI mode)
• Python 3.10+
• At least one LLM provider API key (or Ollama for local inference)
• Windows, macOS, or Linux

Installation

Configuration

Rikugan stores its configuration per host:

You can edit this JSON file directly, or use the Settings dialog in the UI.

Config Structure

{
  "provider": {
    "name": "anthropic",
    "model": "claude-sonnet-4-6",
    "api_key": "sk-...",
    "api_base": ""
  },
  "max_tokens": 16384,
  "temperature": 0.2,
  "context_window": 200000,
  "checkpoint_auto_save": true,
  "max_tool_result_chars": 8000
}

Opening the Panel

Chat & Multi-Tab

Each tab is an independent conversation with its own message history and context.

• New tab: Click the + button
• Close tab: Click the × on the tab
• Fork session: Right-click a tab → "Fork Session" to create a copy at the current point
• Persistence: Tabs are tied to the current file. Opening a different database starts fresh tabs; returning restores saved conversations.

Quick Actions

IDA Pro exposes these in right-click context menus. Binary Ninja has equivalent commands under Tools → Rikugan.

Skills

Skills are reusable analysis workflows. Type / in the input area to see available skills with autocomplete.

Commands

Exploration Mode

Exploration mode is directly inspired by how code agents work, but applied to binaries instead of source code. Instead of analyzing everything in a single context, the orchestrator delegates focused tasks to isolated subagents.

How to use

/explore Analyze this binary and tell me what it does

How it works

1. ORIENT — The orchestrator reads imports, exports, strings, and key functions to build a map of what the binary is doing.
2. DELEGATE — Instead of doing everything in a single context, it spawns subagents and delegates focused tasks to each one: “analyze this function”, “trace this data structure”, “figure out what this import cluster is doing”.
3. ANALYZE — Subagents run in complete isolation from the parent session. They are independent instances of Rikugan with a single task and zero prior knowledge.
4. SYNTHESIZE — Each subagent reports its findings back to the orchestrator, which synthesizes everything and continues toward your goal.

This gives you deeper and faster analysis than a single agent pass, and keeps the main context window clean. During exploration, the agent also renames functions when it has high confidence about what a function actually does.

Natural Language Patching (Experimental)

A binary is code, code is text, and LLMs are good at reading and writing text. /modify does what agentic coding does for source — on the compiled binary.

/modify make this maze game easy to me, make me pass through the walls

Rikugan runs exploration mode, builds context about the binary, and applies the patches. The workflow goes through EXPLORE → PLAN → PATCH → SAVE stages. This can produce issues (segfaults, crashes), but you can feed those back and it will try to fix them.

Research Mode

The /research command performs goal-driven deep analysis of a binary and produces structured documentation. Unlike exploration mode (which gathers context for the agent to act on), research mode outputs Obsidian/Logseq-compatible Markdown files into a notes/ directory — building a persistent knowledge base you can browse, link, and search outside of Rikugan.

Enable Preserve full context in settings to disable tool result truncation during research sessions — ideal when losing decompilation context is worse than higher token cost.

Plan Mode

Plan mode is a simpler two-step workflow: plan first, then execute.

/plan Rename all functions in the crypto module with meaningful names

1. The agent generates a numbered plan
2. You approve or reject the plan
3. The agent executes each step with progress tracking

Bulk Renamer

The bulk renamer agent batch-renames symbols across the binary using subagent orchestration. Instead of renaming functions one by one, the agent analyzes groups of related functions and renames them in coordinated batches.

Mutation & Undo

Every mutating tool call (renames, comments, type changes, prototypes) is automatically recorded with a reverse operation. The Mutation Log panel shows the history.

/undo        # undo last mutation
/undo 5      # undo last 5 mutations

Supported reverse operations: rename_function, rename_variable, set_comment, set_function_comment, rename_data, set_function_prototype, retype_variable. execute_python calls are marked as non-reversible.

Script Approval

The execute_python tool always asks permission before running. You see the full Python code with syntax highlighting in a scrollable preview, and can Allow or Deny each execution.

MCP Servers

Connect external MCP servers to extend Rikugan with additional tools. Create the config file:

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "env": {},
      "enabled": true
    }
  }
}

MCP servers are started in background threads when the plugin loads. Their tools appear with the prefix mcp_<server>_<tool>. Set "enabled": false to keep a server configured without starting it.

The MCP client uses JSON-RPC 2.0 with Content-Length framing and sends periodic heartbeat pings every 30 seconds to detect unresponsive servers. A server is marked unhealthy if a heartbeat times out; it recovers automatically when pings succeed again.

Use /mcp in the chat to check the health status of all connected servers.

Custom Skills

Create custom skills in your user directory:

# IDA Pro
~/.idapro/rikugan/skills/                                        # Linux / macOS
%APPDATA%\Hex-Rays\IDA Pro\rikugan\skills\                       # Windows

# Binary Ninja
~/.binaryninja/rikugan/skills/                                   # Linux
~/Library/Application Support/Binary Ninja/rikugan/skills/       # macOS
%APPDATA%\Binary Ninja\rikugan\skills\                           # Windows

my-skill/
  SKILL.md             # required: frontmatter + prompt body
  references/          # optional: .md files auto-appended
    api-notes.md

Skill Format

---
name: My Custom Skill
description: What it does in one line
tags: [analysis, custom]
allowed_tools: [decompile_function, rename_function]
---
Task: <instruction for the agent>

## Approach
1. First step...
2. Second step...

External Skills & MCP

Rikugan can import skills and MCP servers from Claude Code and OpenAI Codex. This lets you reuse workflows and tool integrations you already have configured in those agents.

Shared Skills

Rikugan discovers skills from:

Both use the same SKILL.md format as Rikugan's own custom skills. Discovered skills appear in Settings → Skills tab, grouped by source. External skills are opt-in — check the ones you want to enable.

Shared MCP Servers

Rikugan discovers MCP server configurations from:

Discovered servers appear in Settings → MCP tab, grouped by source. Like skills, external MCP servers are opt-in — check the ones you want to enable. Once enabled, their tools appear alongside built-in ones with the mcp_<server>_<tool> prefix.

Profiles

Profiles give you granular control over what the agent can see and do. They are especially useful for private or sensitive analysis where you need to prevent data from leaking to the LLM provider.

Built-in Profiles

What Profiles Control

IOC Hexdump Defense

When IOC filters are active, Rikugan also preprocesses hexdump output — raw bytes are decoded, IOC byte positions are identified, and those bytes are zeroed out. This prevents the LLM from reconstructing filtered indicators by reading hex values directly (e.g., decoding 31 39 32 2e 31 36 38 back to 192.168).

Creating Custom Profiles

Open Settings → Profiles and click + New or Clone an existing profile. All settings are edited through the UI. Profiles are saved in your Rikugan config file alongside provider settings.

Persistent Memory

Rikugan automatically creates a RIKUGAN.md file in the same directory as your IDB/BNDB. This file persists across sessions:

• The first 200 lines are loaded into the system prompt on every session
• The agent can save facts via the save_memory pseudo-tool
• Approved plans from exploration mode are also saved here
• Use /memory to view current contents

Chat Export

Right-click a tab or click the Export button to save a conversation as Markdown. Tool calls are formatted with language-appropriate syntax highlighting (c for decompiled code, x86asm for disassembly, python for scripts).

API Key Encryption

All stored API keys can optionally be encrypted at rest using AES-256-GCM with PBKDF2-HMAC-SHA256 key derivation (600,000 iterations). When enabled, plaintext keys are zeroed out in config.json and replaced with a single encrypted blob.

Tools Reference

50 tools are shared across both hosts with identical interfaces. IDA adds 6 host-specific microcode tools; Binary Ninja adds 13 host-specific IL tools for reading, analyzing, and transforming its intermediate language.

Shared Tools (50)

IDA-Only Tools (6)

Binary Ninja-Only Tools (13)

Providers

Config Reference

Config Paths

All paths below are under each host's user directory. IDA Pro shares the same user directory on Linux and macOS (~/.idapro/); Binary Ninja uses a platform-specific location.