recurse

Agentic reverse engineering IDE with a pure-Rust multi-architecture disassembler, native decompiler, debugger, and LLM agent for binary analysis and CTF work.

recurse-agent is only the agent; static analysis lives in recurse-static and the debugger in recurse-debug, so the agent pulls in neither systems code it does not use. No crate depends on Tauri, and each builds/tests standalone; recurse-eval drives the agent headlessly. All are workspace members, so one Cargo.lock and one target/ cover the whole repo.

Features

• Cursor-style workspace: function list, disassembly/strings/imports tabs, CFG graph, and a chat agent sidebar (toggle with the Chat button or Ctrl+L)
• Recon page: binary info, MD5/SHA1/SHA256/CRC32 hashes, entropy, linked libraries, a self-contained hardening report (RELRO / PIE / NX / canary / FORTIFY / RPATH — no external checksec), and analysis counts
• Rename functions from the list (double-click or the ✎ button); names persist in SQLite and show up in the function list, disassembly annotations, and to the agent
• Grounded agent: every address is a clickable object (function list, graph nodes, xrefs, decompiler annotations) — not pasted text that the model can hallucinate
• Live analysis session on any binary — including extension-less files
• Persistent project memory in SQLite with FTS5/BM25 retrieval — renames, findings and notes survive /clear and reopen, and seed the next session
• Headless core (recurse-agent) with per-turn debug tracing; the same agent loop runs in the UI and in the eval harness
• LLM agent backed by an OpenAI-compatible endpoint (OpenRouter by default) with a model picker; drives the session directly (disasm, xrefs, strings, imports, decompile)
• Dark-first UI built with Tailwind CSS v4 + shadcn/ui
• lift op: raises a function into a VTIL-style de-obfuscation IL and runs whole-routine propagation/folding/dead-code-elimination/branch-resolution passes over it — useful when disassembly looks like a VM dispatcher or opaque-predicate chain (see docs/vtil-lift.md)
• Native decompiler: decompile renders C-like pseudocode (if/while structuring, total instruction coverage) from the same recurse-vtil pipeline — no external tool, no r2 required
• Standalone recurse-mcp server: the same Engine over MCP stdio for any MCP-capable agent (Claude Code, Cursor, Claude Desktop, …) — no Tauri, no IDA seat, no Python bridge (see docs/recurse-mcp.md)

Analysis backends

Analysis goes through a single Engine trait (crates/recurse-static/src/engine.rs), so the engine is a choice, not a hard dependency:

• native (default) — pure-Rust ELF/PE/Mach-O parsing and multi-architecture disassembly (object + capstone): x86/x86-64, ARM, AArch64, MIPS, PowerPC, RISC-V, SPARC, SystemZ, M68K, BPF. No child process, no external tool, no LGPL in the build. Includes a decompiler (recurse-vtil's lift → optimize → structure pipeline — see docs/vtil-lift.md) and a lift op for VTIL-style de-obfuscation.
• r2 (radare2) — supported as an opt-in alternative for installs that want its own, more complete decompiler or a raw console. Install r2 and select it as the engine; it runs as a separate process and is never linked or bundled with Recurse.

Pick with the settings menu, the RECURSE_BACKEND environment variable, or the stored config. The agent gets one backend-neutral analyze tool (functions, disasm, graph, lift, decompile, xrefs, strings, imports, info, plus raw for the engine console) — filtered to the ops the active engine actually supports, so raw (native has no console) is only advertised when available. The UI consumes canonical result types, not any engine's JSON. See docs/backends.md for the trait, the crate choices, and the licensing rationale. Opening a large binary is fast because analysis is lazy — discovery indexes functions cheaply and basic blocks decode only when a function is viewed; see docs/lazy-analysis.md.

Why not just MCP-to-IDA / yolo it in Claude Code?

Stapling an MCP server onto IDA/Ghidra, or pasting disassembly into a CLI agent, works for 5-function CTFs and falls apart on real binaries. Recurse is a purpose-built environment, not a chatbot wrapper:

• Binary world-model, not text scraping. Functions, xrefs, strings and the CFG are first-class state shared by the agent and the UI. No re-parsing pdF dumps into context every turn, no invented 0x401023s.
• Verification > generation. In RE there is no npm test — verification is visual. Agent renames propagate to the function list, graph and decompile instantly, so a human confirms or rejects in one click.
• Built for scale. Real malware is 10k functions. Demand-driven tools + persistent memory beat dumping full decompiles until context OOMs.
• Agentable engine. A scriptable, pipeable engine means agents can run 100 turns, fork, reset and diff — and you can actually ship it. The default native engine needs no external tool at all.
• Malware-safe by default. Local-first, BYO-key/OpenRouter routing, and a path to offline models — no forced exfil of samples to a cloud chatbot.

Prerequisites

1. Core toolchains

Verify:

2. Analysis engine

The default native engine is pure Rust — nothing to install. To use r2 (radare2) as the analysis engine instead, install it and select it (the settings menu, or RECURSE_BACKEND=r2); Recurse drives the r2 binary on your PATH. r2 is optional, is never required by the build, and is never distributed with Recurse — bring your own install.

3. Tauri Linux system dependencies

Debian/Ubuntu/Pop!_OS:

Other distros: follow the official Tauri prerequisites.

4. Decompiler

Both engines provide one: native renders pseudocode via recurse-vtil (lift → optimize → structure — see docs/vtil-lift.md), nothing to install; r2 can provide its own, more complete decompiler when its plugin is installed.

Build

App dependencies live in tauri/; Rust comes from the workspace root. just wraps both (see just --list), or drive them directly.

Development

This starts the Vite dev server and launches the Tauri window. First compile takes a while (Rust build); subsequent ones are fast.

Production binary

The bundle lands in target/release/bundle/ (workspace target):

• .deb / .rpm / .AppImage for Linux
• standalone binary at target/release/recurse

On Arch and other rolling distros the AppImage step needs a one-time local fix (upstream linuxdeploy lags the distro toolchain) — see docs/linux-appimage-build.md.

Just the frontend (no desktop shell)

Quality checks

Equivalent direct commands: cargo clippy --workspace --all-targets, cargo test --workspace at the root; npm run lint / npm run format / npm run build inside tauri/.

Evals

The agent is evaluated headlessly against crackme tiers (see crates/recurse-eval/README.md). Tiers are YAML: selection filters over the dataset, or a frozen hexid list, plus run knobs.

eval-run is a binary, not a test, so cargo test never spends money or time on the agent. Endpoint + key go in crates/recurse-eval/.env (copy .env.example). Each run writes target/eval-traces/<tier>/<backend>/run.log (the full narrative) plus one <hexid>.json per task with the complete per-turn conversation. The backend (native or r2) is selectable per run — see the eval README.

Agent LLM

The agent chat panel runs on any OpenAI-compatible endpoint. Configure the API key, base URL, and model from the in-app Model & Provider dialog (persisted in ~/.recurse/recurse.db), or via env:

Local models / custom base URL

Point the agent at any local or self-hosted OpenAI-compatible server — Ollama, LM Studio, llama.cpp's llama-server, vLLM, text-generation-webui, or a remote gateway. Set the Base URL in the dialog (a bare base URL or a full /chat/completions route both work) and pick a model from that server's catalog, or type a model id (llama3.1:8b, qwen2.5-coder, …) directly:

Local endpoints need no API key: when the key is blank the request is sent with no Authorization header, and the model list is read from the endpoint's own {base}/models. A custom endpoint is treated as configured without a key, so the chat works out of the box against a local server.

Without credentials it falls back to an echo client so the wiring stays exercisable.

The agent sees live binary context (arch, bits, type) and can drive the full analysis surface (disassembly, xrefs, strings, imports, decompilation) through the session.

License

Apache-2.0 — © 2026 Aayush Khanna