Rikugan: Instructions file for Codex

AGENTS.md — Rikugan Developer Guide

Project Overview

Rikugan (六眼) is a multi-host reverse-engineering agent plugin that integrates an LLM-powered assistant directly inside IDA Pro and Binary Ninja. It has its own agentic loop, in-process tool orchestration, streaming UI, multi-tab chat, session persistence, MCP client support, and host-native tool sets.

Directory Structure

rikugan/
├── agent/                    # Agent loop & prompt logic (host-agnostic)
│   ├── loop.py               # AgentLoop: generator-based turn cycle
│   ├── turn.py               # TurnEvent / TurnEventType definitions
│   ├── context_window.py     # Context-window management (threshold compaction)
│   ├── exploration_mode.py   # Exploration state machine (4 phases)
│   ├── mutation.py           # build_reverse_record, capture_pre_state, _KNOWN_IRREVERSIBLE
│   ├── plan_mode.py          # Plan-mode step orchestration
│   ├── subagent.py           # SubagentRunner — isolated AgentLoop for tasks
│   ├── system_prompt.py      # build_system_prompt() dispatcher
│   └── prompts/              # Host-specific system prompts
│       ├── base.py           # Shared prompt sections (discipline, renaming, etc.)
│       ├── ida.py            # IDA Pro base prompt
│       └── binja.py          # Binary Ninja base prompt
│
├── core/                     # Shared infrastructure (host-agnostic)
│   ├── artifacts.py          # Oversized tool output: head/tail rendering, artifact:// store
│   ├── chat_context.py       # Which chat the current tool call belongs to (context variable)
│   ├── config.py             # RikuganConfig — settings, provider config, paths
│   ├── constants.py          # Constants (CONFIG_DIR_NAME, etc.)
│   ├── errors.py             # Exception hierarchy (ToolError, AgentError, etc.)
│   ├── host.py               # Host context (BV, address, navigate callback)
│   ├── logging.py            # Logging utilities
│   ├── thread_safety.py      # Thread-safety helpers (@idasync, etc.)
│   ├── types.py              # Core data types (Message, ToolCall, StreamChunk, etc.)
│   └── workspace.py          # Path confinement for file tools, atomic writes, undo backups
│
├── ida/                      # IDA Pro host package
│   ├── tools/
│   │   └── registry.py       # IDA create_default_registry() — imports rikugan.tools.*
│   └── ui/
│       ├── panel.py          # IDA PluginForm wrapper
│       ├── actions.py        # IDA UI hooks & context menu actions
│       └── session_controller.py  # IDA SessionController
│
├── binja/                    # Binary Ninja host package
│   ├── tools/
│   │   ├── registry.py       # BN create_default_registry() — imports rikugan.binja.tools.*
│   │   ├── common.py         # BN shared helpers (get_bv, get_function_at, etc.)
│   │   ├── navigation.py     # Navigation tools
│   │   ├── functions.py      # Function listing/search tools
│   │   ├── strings.py        # String tools
│   │   ├── database.py       # Segments, imports, exports, binary info
│   │   ├── disassembly.py    # Disassembly tools
│   │   ├── decompiler.py     # Decompiler/HLIL tools
│   │   ├── xrefs.py          # Cross-reference tools
│   │   ├── annotations.py    # Rename/comment/set_type tools
│   │   ├── types_tools.py    # Struct/enum/typedef tools
│   │   ├── il.py             # IL core tools (get_il, get_il_block, nop_instructions, redecompile_function)
│   │   ├── il_analysis.py    # IL analysis tools (get_cfg, track_variable_ssa)
│   │   ├── il_transform.py   # IL transform tools (il_replace_expr, il_set_condition, il_nop_expr, patch_branch, etc.)
│   │   └── scripting.py      # execute_python tool
│   └── ui/
│       ├── panel.py          # BN QWidget panel
│       ├── actions.py        # BN action handlers
│       └── session_controller.py  # BN BinaryNinjaSessionController
│
├── tools/                    # IDA tool implementations
│   ├── base.py               # @tool decorator, ToolDefinition, JSON schema generation
│   ├── registry.py           # Shared ToolRegistry class
│   ├── navigation.py         # IDA navigation tools
│   ├── functions.py          # IDA function tools
│   ├── strings.py            # IDA string tools
│   ├── database.py           # IDA database tools (segments, imports, exports)
│   ├── disassembly.py        # IDA disassembly tools
│   ├── decompiler.py         # IDA decompiler tools (Hex-Rays)
│   ├── xrefs.py              # IDA xref tools
│   ├── annotations.py        # IDA annotation tools (rename, comment, set type)
│   ├── types_tools.py        # IDA type tools (structs, enums, typedefs, TILs)
│   ├── microcode.py          # IDA Hex-Rays microcode tools
│   ├── microcode_format.py   # Microcode formatting helpers
│   ├── microcode_optim.py    # Microcode optimizer framework
│   ├── scripting.py          # IDA execute_python tool
│   ├── filesystem.py         # read_file, write_file, edit_file (both hosts)
│   ├── file_search.py        # search_files: ripgrep or Python scan (both hosts)
│   └── shell.py              # run_shell (both hosts)
│
├── hosts/                    # Backward-compat shims → rikugan.ida.ui.* / rikugan.binja.ui.*
│
├── providers/                # LLM provider integrations (host-agnostic)
│   ├── base.py               # LLMProvider ABC
│   ├── registry.py           # ProviderRegistry
│   ├── anthropic_provider.py # Claude (Anthropic) — supports OAuth auto-detection
│   ├── openai_provider.py    # OpenAI
│   ├── gemini_provider.py    # Google Gemini
│   ├── ollama_provider.py    # Ollama (local)
│   ├── minimax_provider.py   # MiniMax (subclasses OpenAICompatProvider)
│   └── openai_compat.py      # OpenAI-compatible endpoints
│
├── mcp/                      # MCP client (host-agnostic)
│   ├── config.py             # MCP server config loader
│   ├── client.py             # MCP protocol client
│   ├── bridge.py             # MCP ↔ ToolRegistry bridge
│   ├── manager.py            # MCPManager — lifecycle management
│   └── protocol.py           # MCP JSON-RPC protocol types
│
├── skills/                   # Skill system (host-agnostic)
│   ├── registry.py           # SkillRegistry — discovery & loading
│   ├── loader.py             # SKILL.md frontmatter parser (mode field support)
│   └── builtins/             # 12 built-in skills
│       ├── malware-analysis/
│       ├── linux-malware/
│       ├── deobfuscation/
│       ├── vuln-audit/
│       ├── driver-analysis/
│       ├── ctf/
│       ├── generic-re/
│       ├── ida-scripting/    # IDAPython API skill with full reference
│       ├── binja-scripting/  # Binary Ninja Python API skill with full reference
│       ├── modify/           # Exploration mode: autonomous binary modification
│       ├── smart-patch-ida/  # IDA-specific binary patching workflow
│       └── smart-patch-binja/ # Binary Ninja-specific patching workflow
│
├── state/                    # Session persistence (host-agnostic)
│   ├── session.py            # SessionState — message history, token tracking
│   └── history.py            # SessionHistory — auto-save/restore per file
│
└── ui/                       # Shared UI widgets (Qt, host-agnostic)
    ├── panel_core.py         # PanelCore — multi-tab chat, export, mutation log, event routing
    ├── session_controller_base.py  # SessionControllerBase — multi-session, fork support
    ├── chat_view.py          # Chat message display widget (queued message support)
    ├── input_area.py         # User input text area with skill autocomplete
    ├── context_bar.py        # Binary context status bar
    ├── message_widgets.py    # Message bubble widgets (tool calls, exploration, approval)
    ├── tool_review.py        # What a tool call will do, laid out for review (diffs, code, not JSON)
    ├── code_view.py          # Read-only code display: syntax scanner, gutter, diff tints
    ├── mutation_log_view.py  # MutationLogPanel — mutation history with undo
    ├── markdown.py           # Markdown rendering for assistant messages
    ├── plan_view.py          # Plan-mode UI
    ├── settings_dialog.py    # Settings dialog (screen-aware sizing)
    ├── styles.py             # Qt stylesheet constants
    └── qt_compat.py          # Qt compatibility layer (PySide6)