Documentation 六眼

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

Requirements

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

Installation

Clone the repository, then run the appropriate installer for your target host.

Clone the repository

git clone https://github.com/buzzer-re/rikugan.git
cd rikugan

Run the installer

IDA Pro (Linux/macOS)

IDA Pro (Windows)

Binary Ninja (Linux/macOS)

Binary Ninja (Windows)

./install_ida.sh

Optional: pass a custom user dir path

./install_ida.sh /path/to/ida/user/dir

install_ida.bat

Optional: pass a custom user dir path

install_ida.bat "C:\Users\you\AppData\Roaming\Hex-Rays\IDA Pro"

./install_binaryninja.sh

Optional: pass a custom user dir path

./install_binaryninja.sh /path/to/binaryninja/user/dir

install_binaryninja.bat

Optional: pass a custom user dir path

install_binaryninja.bat "C:\Users\you\AppData\Roaming\Binary Ninja"

Installers auto-detect the user directory for their host. They create plugin links/junctions, install Python dependencies, and initialize the Rikugan config directory.

Set your API key

Open Rikugan in your disassembler, click Settings, and paste your API key for your preferred provider.

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 a 4-phase autonomous agent flow for binary modification. The agent explores, plans, patches, and saves — with user approval at every gate.

How to use

/modify Change the score constant from 100 to 999

Phases

1. EXPLORE — The agent investigates the binary using all analysis tools. It accumulates findings in a KnowledgeBase (functions, hypotheses, data structures). Runs as a subagent with isolated context.
2. PLAN — The agent synthesizes findings into a numbered modification plan with target addresses, current/proposed behavior, and patch strategy. You must approve the plan.
3. EXECUTE — The agent applies patches in-memory for each planned change using the platform-specific smart-patch skill. Each patch is verified via decompilation.
4. SAVE — You see a summary of all patches (count, bytes modified, verification status). Choose "Save All" to persist or "Discard All" to roll back.

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

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]
mode: exploration
---
Task: <instruction for the agent>

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

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).

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.