ida-agent

English | 中文

Windows x64, Linux x64 and macOS Universal 2 / Windows、Linux、macOS 三平台发布

The Windows packages described below require IDA Professional 9.4 for Windows, with its bundled Qt 6.8.2. Linux and macOS versions have not been comprehensively tested; please report bugs. Check each release's assets for available platforms.

下文的 Windows 安装包需要 Windows 版 IDA Professional 9.4 及其自带的 Qt 6.8.2。Linux 和 macOS 版本尚未经过全面测试，如遇问题请提交 Bug / Issue。 可用平台以各次发布的附件为准。

Download releases / 下载发布版本 · Usage guide · 中文使用指南

Linux preview / Linux 预览

Ubuntu 24.04 · IDA Professional 9.4 · ida-agent 0.4.10.

Real Linux UI captured at 100% scaling (1920 × 1080), showing pseudocode, AI Chat, syntax-highlighted code and the Effort selector. The binary and conversation are demonstrations. Click the image to open the original PNG.

100% 缩放实机截图（1920 × 1080），展示伪代码、AI Chat、代码语法高亮和 Effort 推理强度选择。程序与对话内容均为演示示例；点击图片查看原始 PNG。

English

ida-agent combines an IDA plugin, an MCP Gateway for external AI clients, and a built-in AI Console. It supports function and cross-reference inspection, pseudocode, bounded argument tracing across direct callers, guard evidence extraction, and supported IDB edits through ChangeSets.

This repository contains the ida-agent source, usage guides and binary releases. Project-owned code is licensed under MIT; dependencies retain their own terms in THIRD_PARTY_NOTICES.md. Pushes run the public build checks; matching v* tags trigger release packaging and publication. The private repository is retained for archival storage and restricted Qt build inputs. Source synchronization and its credential are no longer required. Maintainer setup is documented in release/README.md. See the source build guide. Older release tags created before source publication keep their original documentation snapshots; clone main for current source or use the named release assets to install ida-agent.

Install

1. Download ida-agent-<version>-windows-x64-setup.exe from Releases and close IDA before installing or upgrading. The installer installs for the current Windows user and deploys the IDA plugin.
2. Alternatively, extract ida-agent-<version>-windows-x64.zip, then copy plugins/ida-agent-plugin.dll into your IDA user plugin directory. Keep the Gateway and skills together in the extracted directory.
3. Start IDA and load a database. Open Edit → Plugins → IDA Agent.
4. When upgrading from before 0.4.0, uninstall the old package and remove its old client entry before configuring ida-mcp. For 0.4.4 tool-name changes, follow the upgrade section in the usage guide.

The installer has a separate .sha256 file; the portable ZIP includes per-file SHA256SUMS.txt. IDA itself and Qt runtime DLLs are not bundled.

Starting with v0.5.0, Ubuntu 24.04+ / Debian 13+ amd64 packages include a
.deb installer. Close IDA, install the downloaded file with
sudo apt install ./ida-agent-VERSION-linux-x64.deb, then open IDA Agent from
the application menu. The window has the shared product icon, supports English
and Chinese, and installs the plugin for your IDA user directory. Open manager
opens client configuration in your browser; the Gateway is /usr/bin/ida-mcp.
v0.5.0 新增 Linux .deb 安装包：安装后从应用菜单打开带图标的 IDA Agent，
选择 IDA 用户目录并点击 安装插件，或点击 打开管理页 配置外部客户端。

The tar.gz portable package remains available. For installation, migration,
uninstallation and the idat-with-agent headless wrapper, see the
Linux installation guide / Linux 安装指南.

For macOS, open the DMG and run IDA Agent Installer.app. It installs the
Universal 2 plugin and Gateway for the current user. The .command launcher opens
the configuration manager. macOS uses native networking and needs no OpenSSL.
The binaries use ad-hoc signatures without Developer ID notarization. See the
included installation instructions. Close IDA before installing either platform.

Configure a provider

Open Provider Settings..., select the OpenAI or Claude preset, or add a custom provider. Set the API mode, Base URL, and API key. Use Refresh Models or Add Model..., choose a default model/provider, save, then open Open AI Chat.

Version 0.5.0 and later also support Ctrl+Shift+A to open AI Chat or focus its input if already open. Customize Open AI Chat (ida-agent:ai:open) in IDA's shortcut settings.

Enter the API prefix, not a complete operation URL. Test Connection checks model discovery, not chat, streaming, or tool-calling compatibility. Providers without model discovery may work with a manually added model.

API keys and saved proxy passwords are stored as plaintext with current-user file permissions, normally in %LOCALAPPDATA%\ida-agent\ai\providers.json. The built-in AI sends conversation content and relevant analysis results to the selected provider. External MCP clients use their own provider settings.

AI Chat 0.4.9 includes a full-height right sidebar with Agent-style roles and emojis, balanced message spacing, Markdown, syntax-highlighted code blocks, per-message/code copy and bounded incremental streaming, plus an Effort selector beside the input. It saves reasoning strength for the selected model and is disabled during active requests. See the AI Chat rendering and effort reference.

Analysis memory and workflows

Enable Tools for the selected model. Use /memory add <note>, /memory add-local <note>, /memory search <text>, and /memory forget <id> to manage this binary's external analysis memory. /new and /clear keep saved notes. Use /workflow protection [question], /workflow function [question], or /workflow types [question] for reports with actual tool evidence and explicit coverage gaps. Agent memory writes follow the conversation approval policy. See the full command and IDA 9.5 acceptance reference.

Project instructions are checked once in the current IDB directory, in the order AGENTS.md, Agents.md, then agents.md. Later requests, new conversations and context compaction reuse the cached result, including a missing file. Use /instructions to view its status and /instructions reload to read changes while chat is idle; switching projects or reopening the database also refreshes it. A complete UTF-8 file up to 32 KiB is included as required model context. Project rules take priority over historical notes; current user instructions and the live approval policy retain priority. See the project instruction reference.

These features are included in v0.4.9 and later packages. The stable UI ABI remains IDA 9.4 / Qt 6.8.2; the Windows 9.5 experimental path requires strict ABI preflight and still needs live acceptance.

MCP clients

Run ida-mcp.exe -web for the local client configuration manager, or configure your MCP client to start ida-mcp.exe with no arguments for stdio. Keep IDA open with the database loaded. Optional HTTP transport binds only to loopback; authenticated remote hosting is not implemented.

The configuration manager supports Codex, OpenCode 2, Claude Code, Antigravity CLI, Grok Build, and ZCode. ZCode uses the user-level ~/.zcode/cli/config.json (mcp.servers), with optional skills under ~/.zcode/skills/.

For OpenCode 2, use Scoop versions/opencode2 or npm @opencode/cli@2; launch it with opencode. The manager installs its MCP configuration under mcp.servers.ida-mcp, preserving unrelated settings and upgrading only the old IDA entry. See the OpenCode 2 setup guide.

On Windows, the manager also discovers Codex in common npm/Scoop installations and the desktop app's bundled CLI when PATH is outdated. It runs the native executable without requiring Node.js in PATH. For custom installations, set IDA_MCP_CODEX_PATH to the absolute path of codex.exe and restart the manager.

Limits and build environment

• Pseudocode and semantic analysis require a compatible Hex-Rays decompiler and license. Caller tracing expands known direct callers, defaults to two levels, and permits at most five. Unknown indirect calls, native tail calls, callee-return summaries, and heap aliases are not recovered.
• Guard evidence is function-local and does not prove safety, exploitability, or complete input validation. General cross-reference tracing is not semantic taint analysis. Results may be partial or truncated.
• Only supported ChangeSet edits offer preview/apply/rollback. Arbitrary scripts are not sandboxed or automatically reversible.
• The Windows build configuration uses MSVC 2022 x64, Windows SDK, CMake 3.25+, Ninja, Go 1.25.0+, Python 3.11, and Inno Setup 6. It links public IDA SDK import libraries against Qt 6.8.2 headers; runtime Qt comes from IDA.
• CI checks compilation and unit tests. Those checks do not replace live IDA UI or licensed integration testing.

中文

ida-agent 包含 IDA 插件、供外部 AI 客户端使用的 MCP Gateway，以及内置 AI Console。支持函数与交叉引用检查、伪代码、沿直接调用者进行有限层级的参数回溯、校验证据提取，以及通过 ChangeSet 执行支持的 IDB 修改。

本仓库包含 ida-agent 源码、使用说明和二进制版本。项目自有源码采用 MIT 许可证，第三方依赖保留各自许可，见 THIRD_PARTY_NOTICES.md。提交推送会触发公开构建检查，匹配版本号的 v* 标签会触发打包发布。私有仓库保留为历史存储和受限 Qt 构建输入的存放位置，不再需要定时源码同步或同步凭据。维护者配置见 发布配置说明。编译步骤见中文源码说明。公开源码之前创建的发布标签保留原文档快照；获取当前源码请克隆 main，安装软件请使用带有 ida-agent 名称的发布附件。

安装

1. 从 Releases 下载 ida-agent-<版本>-windows-x64-setup.exe，安装或升级前关闭 IDA。安装器按当前 Windows 用户安装，并部署 IDA 插件。
2. 也可以解压 ida-agent-<版本>-windows-x64.zip，将 plugins/ida-agent-plugin.dll 复制到 IDA 用户插件目录。Gateway 与技能目录保留在便携目录中。
3. 启动 IDA 并加载数据库，在 Edit → Plugins → IDA Agent 中使用插件。
4. 从 0.4.0 之前的版本升级时，先卸载旧包并移除旧客户端条目，再配置 ida-mcp。0.4.4 的工具名变化见使用指南中的升级说明。

安装器附带独立 .sha256 校验文件，便携 ZIP 内含逐文件 SHA256SUMS.txt。发布包不包含 IDA 或 Qt 运行时 DLL。

Linux：解压 tar.gz，校验 SHA256SUMS.txt，关闭 IDA 后将
plugins/ida-agent-plugin.so 放入 ${IDAUSR:-$HOME/.idapro}/plugins/，保留
ida-mcp 与 skills/。系统需安装 OpenSSL 3 和 CA 证书，Qt 使用 Linux IDA 9.4
自带版本；详细步骤见包内 README.md。
无界面模式使用包内 idat-with-agent /绝对路径/ida-9.4/idat 并附加原有 IDA 参数，
以便 IDAT 加载对应的 Qt 库。

macOS：打开 DMG，运行 IDA Agent Installer.app，按当前用户安装 Intel /
Apple Silicon 通用插件和 Gateway。安装后的 .command 启动配置管理页。使用系统
原生网络接口，无需 OpenSSL；二进制采用临时签名，未做 Developer ID 公证。
安装前关闭 IDA，详细步骤见包内说明。

配置供应商

打开 Provider Settings...，选择 OpenAI、Claude 预设或添加自定义供应商，填写 API 模式、Base URL 和 API Key。通过 Refresh Models 获取模型，或用 Add Model... 手动添加模型 ID，设置默认模型和供应商，保存后打开 Open AI Chat。

0.5.0 及后续版本支持 Ctrl+Shift+A 打开 AI Chat；窗口已打开时直接聚焦输入框。可以在 IDA 快捷键设置中修改 Open AI Chat（ida-agent:ai:open）的按键。

支持 OpenAI 风格的 Responses / Chat Completions 和 Anthropic 风格的 Messages。Base URL 填 API 前缀，例如 https://api.openai.com/v1，不要附加 /responses、/chat/completions 或 /messages，插件会自动追加。Test Connection 只检查模型列表接口，不能证明聊天、流式输出和工具调用均兼容；不支持模型列表的服务可尝试手动添加模型。

API Key 和已保存的代理密码使用当前用户文件权限保护，但以明文保存，通常位于 %LOCALAPPDATA%\ida-agent\ai\providers.json。内置 AI 会向选定供应商发送会话内容与相关分析结果。外部 MCP 客户端使用其自己的模型供应商配置。

0.4.9 的 AI Chat 默认停靠在全高右侧栏，支持 Agent 样式的角色分层与 Emoji、适中的消息间距、Markdown、带语法高亮的代码块及消息/代码复制，并对流式刷新和长对话显示设置性能预算。输入行旁的 Effort 选择器可设置当前模型的推理强度；请求运行时暂不可修改。详见AI Chat 渲染与推理强度说明。

分析记忆与工作流

在所选模型中启用 Tools。用 /memory add <笔记>、/memory add-local <笔记>、/memory search <关键词> 和 /memory forget <编号> 管理当前二进制的外部分析记忆。/new、/clear 保留已存笔记。/workflow protection [问题]、/workflow function [问题]、/workflow types [问题] 分别提供保护强度评估、函数与数据流调查、类型恢复准备；报告使用实际工具证据并明确未完成的范围。Agent 的记忆写入沿用会话审批。详见完整命令与 IDA 9.5 验收说明。

项目规则首次使用时在当前 IDB 所在目录按 AGENTS.md、Agents.md、agents.md 的顺序检查，后续请求、新建会话和上下文压缩均复用缓存；未找到文件的结果也会缓存。聊天空闲时用 /instructions 查看状态，用 /instructions reload 读取文件变更；切换项目或重新打开数据库也会刷新。32 KiB 以内的完整 UTF-8 文件会作为必要模型上下文发送。项目规则优先于历史记忆，当前用户指令和会话审批策略仍保留优先级。详见项目规则说明。

上述功能包含在 v0.4.9 及后续发布包中。稳定 UI ABI 仍是 IDA 9.4 / Qt 6.8.2；Windows 9.5 实验路径要求严格 ABI 预检，实机验收仍待完成。

MCP 客户端

运行 ida-mcp.exe -web 打开本地配置管理页，或让 MCP 客户端以无参数方式启动 ida-mcp.exe 使用 stdio。使用时保持 IDA 与数据库打开。可选 HTTP 模式仅监听本机回环地址，尚未实现带认证的远程服务。

配置管理页支持 Codex、OpenCode 2、Claude Code、Antigravity CLI、Grok Build 和 ZCode。ZCode 使用用户级 ~/.zcode/cli/config.json 中的 mcp.servers，可选技能位于 ~/.zcode/skills/。

OpenCode 2 使用 Scoop 的 versions/opencode2 或 npm 的 @opencode/cli@2，启动命令仍为 opencode。管理页将 MCP 配置写入 mcp.servers.ida-mcp，保留其他设置，只升级旧的 IDA 条目。详见 OpenCode 2 安装说明。

Windows 下，管理页也会检查常见 npm/Scoop 安装位置及 Codex 桌面应用自带的 CLI，避免旧 PATH 导致检测失败；优先运行原生程序，不依赖 PATH 中的 Node.js。自定义安装位置可通过 IDA_MCP_CODEX_PATH 指定 codex.exe 的绝对路径，设置后重启管理页。

当前限制与编译环境

• 伪代码和语义分析需要对应的 Hex-Rays 反编译器与许可。跨函数追踪只展开已知直接调用者，默认两层、最多五层；不恢复未知间接调用、原生尾调用、被调函数返回值摘要或堆别名。
• 校验证据仅覆盖函数内部，不能证明安全、可利用性或输入校验完备。普通交叉引用追踪不是语义污点分析，结果可能不完整或被预算截断。
• 只有支持的 ChangeSet 修改提供预览、应用和回滚；任意脚本没有沙箱，也不会自动回滚。
• Windows 构建配置使用 MSVC 2022 x64、Windows SDK、CMake 3.25+、Ninja、Go 1.25.0+、Python 3.11 和 Inno Setup 6。编译使用 Qt 6.8.2 头文件与公开 IDA SDK 导入库，运行时使用 IDA 自带 Qt。
• CI 编译与单元测试通过，不能替代真实 IDA 的 UI 或需要许可的集成测试。

Version 0.5.2 / 0.5.2 版本

Version 0.5.2 fixes AI Chat: Claude tool calls without arguments, long OpenAI Responses turns, cancellation after a tool-call reply, chat history overwriting and pruning, and truncation of large selections sent to the chat input. See the release notes.

0.5.2 修复 AI Chat 的多个问题：无参数的 Claude 工具调用、较长的 OpenAI Responses 对话、工具调用回复后的取消、聊天历史的覆盖与清理，以及发送到输入框的大段选区被截断。详见发布说明。

Version 0.5.0 / 0.5.0 版本

Version 0.5.0 adds a Linux .deb installer for Ubuntu 24.04+ and Debian 13+ amd64, with application-menu and window icons, English/Chinese setup, and per-user plugin installation. AI Chat opens with Ctrl+Shift+A. Portable Linux packages remain available. See the release notes and Linux installation guide.

0.5.0 新增面向 Ubuntu 24.04+ / Debian 13+ amd64 的 Linux .deb 安装包，包含应用菜单与窗口图标、中英文设置界面和用户级插件安装。Ctrl+Shift+A 可打开 AI Chat，继续提供 Linux 便携包。详见发布说明和Linux 安装指南。

Version 0.4.9 / 0.4.9 版本

Version 0.4.9 adds the right-side Agent-style chat view, code syntax highlighting, the per-model Effort selector, analysis memory/workflows, prompt and tool-recovery improvements, and cached project instructions. Use /instructions to view the cache and /instructions reload to refresh it. See the release notes.

0.4.9 加入右侧 Agent 样式聊天区、代码高亮、按模型保存的 Effort、分析记忆与工作流、提示词和工具恢复优化，以及项目规则首次读取后的缓存。/instructions 查看缓存状态，/instructions reload 手动刷新。详见发布说明。

Version 0.4.8 / 0.4.8 版本

Version 0.4.8 makes OpenCode 2 the configuration manager's default OpenCode target. It migrates the managed IDA entry to the native v2 format while preserving other servers, settings, and comments. Install Scoop's versions/opencode2 or npm's @opencode/cli@2, then use Install MCP / Update MCP. See the setup guide and release notes.

0.4.8 的配置管理页默认面向 OpenCode 2，将受管理的 IDA 条目迁移到 v2 原生格式，并保留其他服务器、设置和注释。先安装 Scoop 的 versions/opencode2 或 npm 的 @opencode/cli@2，再点击 Install MCP / Update MCP。详见安装说明和发布说明。

Version 0.4.7 / 0.4.7 版本

Version 0.4.7 adds automatic stable-release checks to the Qt plugin and local Web manager, with shared daily caching, an opt-out, manual checks, and a release-page link. Close IDA and install the complete 0.4.7 package to enable these controls. See the usage guide and release notes.

0.4.7 新增正式版自动更新检测：Qt 插件和本地 Web 管理页共享每日检查缓存，支持关闭自动检测、手动检查和打开下载页面。关闭 IDA 并安装完整的 0.4.7 发布包即可使用。详见使用指南和发布说明。

Version 0.4.6 / 0.4.6 版本

Windows streamed chat now waits asynchronously through delayed headers and SSE frames, fixing the request-state failure that could produce WinHTTP error 12019. External history also works before an IDB's .i64 is packed and retains the same database identity afterward. Install the complete package with IDA closed and restart IDA.

This version adds official Python SDK regression tests across Windows/Linux/macOS and reproducible Codex, Claude Code and OpenCode test entry points. SDK runs use simulated RPC peers; actual Agent/model and licensed IDA results are recorded separately. The 23-tool catalog and existing RPC contracts are preserved. See the release notes and client regression guide.

Windows 流式聊天改为异步等待延迟响应头及 SSE 数据，修复可能触发 WinHTTP 12019 的请求状态错误。数据库 .i64 尚未打包时也能保存外部聊天历史，打包后仍使用同一数据库标识。升级时关闭 IDA、安装完整发布包，再重启 IDA。

本版增加 Windows/Linux/macOS 官方 Python SDK 回归，以及 Codex、Claude Code、OpenCode 的可复现测试入口。SDK 使用模拟 RPC 后端；真实 Agent/模型和需要许可的 IDA 结果单独记录。23 个工具及既有 RPC 合同保持兼容，详见发布说明和客户端回归说明。

Version 0.4.4 / 0.4.4 版本

All clients now use the same 11 underscore-named MCP tools, including ida_instances, ida_functions, and ida_scripts. The fixed catalog and former Grok compatibility behavior are defaults in both stdio and HTTP; no --grok flag is needed. Existing flags are accepted as a deprecated no-op.

Update custom tool allowlists/scripts from names such as ida.functions to ida_functions, refresh packaged skills, and restart the Gateway and client. Specific method identifiers such as function.search and ida.instances.list keep their dots. Follow list → describe → call; see the English usage guide for configuration, all 11 tools, dispatch examples and troubleshooting.

所有客户端现在统一使用 11 个下划线 MCP 工具名，包括 ida_instances、ida_functions 和 ida_scripts。stdio 与 HTTP 默认使用固定目录和原 Grok 兼容行为，无需 --grok；旧参数仍作为已弃用的空操作接受。

将自定义工具允许列表、脚本中的 ida.functions 等旧工具名改为 ida_functions，刷新包内技能，再重启 Gateway 与客户端。function.search、ida.instances.list 等具体方法标识保留点号。使用 list → describe → call；安装、配置、全部 11 个工具、调用示例和常见问题见中文使用指南。

Version 0.4.5 / 0.4.5 版本

The Gateway now exposes 23 fixed underscore-named tools: 12 common direct tools plus the existing 11 domain tools. Direct reads use a simple parameter schema and can route to the sole available instance. Argument failures return field-level tool errors and recovery hints. Bounded per-instance waiting and read-only busy retries reduce transient failures; writes, scripts and debugger control are never automatically retried. Optional -diagnostics writes metadata to stderr.

Restart the Gateway and reconnect the client to refresh its catalog, skill copies and tool allowlists. Direct tools return the operation result directly; existing domain calls keep their method/result envelope. See the English guide and 中文指南 for examples and timeout recovery.

Gateway 固定目录增加为 23 个下划线工具：12 个常用直接入口及原有 11 个领域入口。直接读取工具使用简单参数 schema，并支持唯一实例自动路由；参数错误包含具体字段与修正提示。每实例有界等待和只读忙碌重试减少瞬时失败；修改、脚本和调试控制不会自动重试。-diagnostics 可向 stderr 输出脱敏元数据。

更新后重启 Gateway 并重连客户端，刷新目录、技能和工具允许列表。直接工具返回业务结果，既有领域调用保持 method/result 包装。超时不代表已启动操作被撤销，恢复方式见使用指南。

Build from source / 从源码编译

git clone --recurse-submodules https://github.com/ackwrap/ida-pro-agent.git
cd ida-pro-agent
go -C ida-mcp build ./...

The public SDK stays pinned as a submodule. Full Windows plugin builds use the
tracked Qt headers and public SDK imports; Linux basic MCP/backend tests require
no private Qt bundle. Full Linux/macOS AI panel builds require the Qt inputs from
your IDA 9.4 installation. Detailed toolchains, build commands and testing are in
English source documentation,
中文源码文档,
Linux instructions, and
macOS instructions.

公开 SDK 以固定版本子模块提供。Windows 完整插件使用仓库内 Qt 头文件和公开 SDK
导入库；Linux 基础 MCP/AI 后端测试不需要私有 Qt 包。Linux/macOS 完整 AI 面板编译
需要从自己的 IDA 9.4 安装准备 Qt 输入，详细步骤见上述源码文档。