> For the complete documentation index, see [llms.txt](https://docs.hex-rays.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hex-rays.com/add-ons/assist/getting-started.md).
# Getting Started
Get up and running with Assist: an AI harness for reverse engineering, built directly into IDA.
This tutorial walks you through installation and first setup. Once installed, the Assist panel opens by default. If you close it, reopen it with Ctrl+Shift+K or from **View → Assist**. You can also use Assist from the right-click context menu on a selection, when available.
## Prerequisites
* IDA 9.4 SP1 or later (IDA Home, IDA Pro)
* A Hex-Rays account with access to Assist
* [HCLI](https://hcli.docs.hex-rays.com/) 0.25.0 or later, the Hex-Rays command-line tool (recommended)
## Installation
### Recommended: install with hcli
hcli installs Assist from the Hex-Rays plugin portal and keeps it up to date.
1. **Install hcli.** Follow the [hcli installation guide](https://hcli.docs.hex-rays.com/install).
2. **Log in to your Hex-Rays account.** Assist can only be downloaded by accounts that have access to it, so hcli must be logged in before it can install Assist:
```bash
hcli login
```
3. **Install Assist:**
```bash
hcli plugin install hexrays/assist
```
hcli installs Assist in your IDA user plugins directory (`$IDAUSR/plugins/assist/`), not in the IDA installation folder.
4. **Restart IDA.**
### Update Assist
While IDA is open, Assist checks `hexrays.plugins.hex-rays.com` anonymously shortly after startup and once an hour thereafter to see if a newer release is available for your IDA version and platform. Checking only looks: nothing is downloaded automatically.
When a newer version is available, Assist displays a notice with the upgrade command:
```bash
hcli plugin upgrade hexrays/assist
```
Run the command and restart IDA to load the new version. You can turn **Check for updates automatically** on or off, or run a manual check, under **Settings → Preferences… → Updates** (or `/update`).
`hcli plugin status` shows the installed version and whether an upgrade is available.
### Alternative: install manually
1. Download the Assist archive for your platform from the [My Hex-Rays portal](https://my.hex-rays.com/dashboard/download-center).
2. Extract `plugins/assist/` from the archive into your IDA user directory (see `INSTALL.txt` in the archive):
* macOS and Linux: `~/.idapro/plugins/assist/`
* Windows: `%APPDATA%\Hex-Rays\IDA Pro\plugins\assist\`
The plugin binary is:
* macOS: `assist.dylib`
* Linux: `assist.so`
* Windows: `assist.dll`
The archive also installs `plugins/assist/bin/assist` (`assist.exe` on Windows), the stdio bridge that external MCP clients use.
You can also install the downloaded archive with HCLI: `hcli plugin install ida-assist---.zip`.
{% hint style="warning" %}
**macOS:** the Assist add-on is not codesigned. On first launch macOS may block it. Ad-hoc sign it once after installing: `codesign --force --sign - ~/.idapro/plugins/assist/assist.dylib`. On a managed corporate machine you may need administrator help to allow the add-on.
{% endhint %}
## First run
1. Open IDA and load the binary you want to analyze.
2. The Assist panel opens by default. If you closed it, press Ctrl+Shift+K, or navigate to **View → Assist**.
The first time you open Assist, the **Set up Assist** window walks you through five short steps, plus one optional step: **Welcome**, **Model**, **Permissions**, **The panel**, **Ready**, and optionally **Other agents**. The sections below follow these steps.
If you close the wizard before connecting an agent, you can resume setup from the empty-state card in the panel. Once Assist is configured, every choice from the wizard stays editable under **Settings → Permissions** and **Settings → Preferences…**.
### Choose and configure a model
Select which agent backend Assist will drive. Assist found the models installed on your machine and proposes a possible setup.
Assist organizes the backends into two groups:
| Backend | Group | Sign-in and setup |
| ----------------------------------------- | -------------------------------- | --------------------------------------------------------------- |
| **ChatGPT account** | Assist agent loop | Browser sign-in |
| **Grok** | Assist agent loop | Browser sign-in |
| **Claude Code** | Assist agent loop | Local `claude` CLI installed and signed in |
| **Antigravity CLI** | Assist agent loop | Local `agy` CLI installed and signed in |
| **API key or OpenAI-compatible endpoint** | Assist agent loop | One of 170+ built-in presets, or any custom HTTP/HTTPS endpoint |
| **OpenCode** | External agent, separate process | Local `opencode` CLI installed |
The **Assist agent loop** backends support the full set of features: conversation rollback, fork, the conversation tree, `/fulltriage`, and action conversations. **OpenCode** doesn't. For the effort, speed, and context controls of each backend, see [Settings & Commands → Agent](/add-ons/assist/reference/settings-and-commands.md#agent-agent).
When you choose **API key or OpenAI-compatible endpoint**, the searchable **Agent** picker includes more than 170 built-in presets across 130+ providers: cloud model providers with plan and region selectors, gateways such as OpenRouter and LiteLLM, and local servers such as Ollama and LM Studio. **Custom endpoint...** covers any other OpenAI-compatible server.
{% hint style="info" %}
Consumer account subscriptions (**ChatGPT account**, **Grok**, **Claude Code**, **Antigravity CLI**) and inference API keys are different credentials: you can't paste a consumer subscription as an API key. You can change the agent later from the **Model** bar at the bottom of the panel, or in **Settings → Preferences… → Agent** (`/agent`).
{% endhint %}
{% hint style="info" %}
**Working offline.** For a local-only or air-gapped setup, choose **API key or OpenAI-compatible endpoint** and point it at a locally hosted or internal server, such as Ollama or LM Studio. Also turn off **Check for updates automatically** in **Settings → Preferences… → Updates**. Python and shell commands and external agents that you allow can still reach the network. See [Overview → Agent backends](/add-ons/assist/overview.md#agent-backends).
{% endhint %}
### Settle permissions
Decide what Assist is allowed to do. Reading the database is always allowed; pick one of three presets for everything else:
* **Look, don't touch**: reads project files freely; asks before reading outside the project, writing files, modifying the database, saving memories locally, or sending them to linked databases; keeps Python and shell commands **Off**.
* **Ask before changes** (recommended): reads project files freely and asks before modifying the database, writing files, reading outside the project, running Python or shell commands, saving memories locally, or sending them to linked databases.
* **Work freely**: modifies the database, writes files, and runs Python and shell commands without prompting; asks before reading files outside the project, saving memories locally, or sending them to linked databases.
You can change it later in **Settings → Permissions**. See [Permissions & Privacy](/add-ons/assist/concepts/permissions-and-privacy.md).
### Explore the Assist panel
Assist is dockable like any other IDA view, but has its own specific parts. The panel has five areas:
* **Status** header, with **New** (start a fresh conversation) and **Settings**.
* **Conversation**: the transcript.
* **Suggestions**: ranked [suggestion pills](/add-ons/assist/reference/glossary.md#suggestion-pill) above the composer.
* [**Composer**](/add-ons/assist/reference/glossary.md#composer): where you type, with the `@`, `#`, and `/` prefixes.
* **Model** bar at the bottom, with the model, effort, and speed pickers.
More options, like Memory or Permissions, you'll find under **Settings**.
### Go with the first prompt
Pick one of the suggested prompts to see Assist in action right away, or start from an empty composer.
Once configured, Assist is ready and opened as an IDA view. Type a prompt or use the proposed one, mention a function with `@`, reference an address with `#`, or run a slash `/command` from the start of the input.
### Bring your terminal agent (optional)
If you also work in Claude Code, Codex, Grok, or Antigravity CLI, they can use this database through Assist, with the permissions you just chose. If you only use the panel, there is nothing to do here.
Pick your agent's tab and run the command it gives you in a terminal. The first time it connects, IDA asks whether to allow it. For any other MCP client, such as Cursor or Gemini CLI, copy the `mcp.json` or `config.json` entry instead.
External clients connect through the bundled stdio bridge:
* macOS and Linux: `~/.idapro/plugins/assist/bin/assist --mcp`
* Windows: `%APPDATA%\Hex-Rays\IDA Pro\plugins\assist\bin\assist.exe --mcp`
To find these commands later, open **Settings → Preferences… → Sharing & network → Mesh MCP** (`/sharing`). See [Assist Mesh → Assist MCP](/add-ons/assist/concepts/mesh.md#assist-mcp).
## Triage
When you open a binary with functions for the first time with an **Assist agent loop** backend connected, Assist offers a one-time **Triage this binary** [suggestion pill](/add-ons/assist/reference/glossary.md#suggestion-pill) above the composer. Click it, or type `/fulltriage` at any time, to run a full binary triage pass:
1. **Deterministic harvest.** Assist scans ten binary-level categories (binary type, architecture, compiler, language, debug info, existing local types, segments, code structure, naming coverage, and libraries and imports) without spending model tokens.
2. **Triage conversation.** Assist opens a dedicated **Triage** [action conversation](/add-ons/assist/reference/glossary.md#action-conversation), seeded with the harvested facts, so the model can summarize the binary and recommend where to start.
3. **Evidence-gated memory.** When the **Triage** conversation completes, findings backed by concrete [evidence anchors](/add-ons/assist/reference/glossary.md#evidence-anchor) are saved to the binary's [memory](/add-ons/assist/concepts/memory.md), as long as **Allow memory writes** is on (the default). Claims without evidence are rejected.
A few things to know:
* **Requires the Assist agent loop.** External agents (**OpenCode** and external MCP clients) can't run `/fulltriage`.
* **Requires an input file digest.** Triage keys its state to the digest of the input file that IDA recorded. Databases created from raw memory dumps or carved segments without one can't run `/fulltriage`. The automatic **Triage this binary** offer also needs at least one function in the database; `/fulltriage` doesn't.
* **Scales down on large binaries.** On large databases, `/fulltriage` and the whole-binary scan tools sample functions and cap per-category inventories, so the analysis stays responsive.
## Working in the panel
* **Mention context**: type `@` to reference a function or `#` to reference an address. The picker searches the database as you type.
* **Right-click actions**: right-click in Disassembly, Pseudocode, Hex View, Functions, Imports, or Exports to open context-specific actions under **IDA Assist**, plus the **Repair** and **Memory** submenus. Model-assisted actions open a scoped action conversation and draft a prompt into the composer, so you can review, edit, or **Dismiss** it before sending. See [Right-click context menus](/add-ons/assist/concepts/tools-and-actions.md#right-click-context-menus-ida-assist).
* **Suggestion pills**: context-sensitive suggestions appear above the composer as you navigate. Click one to draft an action, or dismiss it with `×`. See [Proactive suggestion pills](/add-ons/assist/concepts/tools-and-actions.md#proactive-suggestion-pills).
* **Prompt queue**: if you submit a prompt while a turn is running, it waits in a queue above the composer and runs when the current turn finishes. From the queue you can **Send now** (or press Enter with an empty composer) to interrupt the running turn and run it first, **Edit** it, **Pause** or **Resume** the queue, or **Cancel** an item. Tool calls that have already completed aren't undone.
* **Custom system prompt**: add standing instructions for your project or team under **Settings → Preferences… → Agent → Custom system prompt** (`/agent`).
* **Conversation history**: conversations are saved automatically on disk, with no opt-out, and the most recent one is restored when you reopen the database. **New** in the **Status** header starts a fresh conversation. See [Where Assist stores data](/add-ons/assist/reference/diagnostics.md#where-assist-stores-data).
* **Sessions**: open **Settings → Sessions** (`/sessions`) to search, **Resume**, **Export**, or **Delete** past conversations, and to review their database edits and script calls with **View write activity**.
* **Keyboard**: Ctrl+Shift+K toggles the panel, Enter sends, Shift+Enter inserts a new line, Esc interrupts a running turn, and Up/Down recall previous prompts.
### Slash commands
Type `/` at the start of the composer to run a panel command, such as `/fulltriage` (run binary triage), `/compact` (compress the conversation history), `/tree` (open the conversation tree), `/sessions`, `/memory`, `/permissions`, `/privacy` (confidentiality rules), `/agent`, or `/export` (export as HTML). Text that doesn't match a command is sent as an ordinary message. For the full list, see [Settings & Commands → Slash commands](/add-ons/assist/reference/settings-and-commands.md#slash-commands).
## Privacy and permissions
Before sending sensitive data to a cloud model, review [Permissions & Privacy](/add-ons/assist/concepts/permissions-and-privacy.md):
* **Confidentiality rules** (`/privacy`) mask sensitive function names, variable names, string literals, binary names, or patterns that Assist sends. The rules are empty on a fresh install.
* **Permissions** (`/permissions`) show which capabilities are **On**, **Ask when needed**, or **Off**.
{% hint style="warning" %}
Conversations are saved locally on disk **without** confidentiality masking. See [Sessions](/add-ons/assist/reference/glossary.md#saved-session) and [Where Assist stores data](/add-ons/assist/reference/diagnostics.md#where-assist-stores-data).
{% endhint %}
## What's next
* See [Concepts](/add-ons/assist/concepts.md) for how Assist works under the hood.
* See [Reference](/add-ons/assist/reference.md) for every setting, slash command, and built-in tool.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.hex-rays.com/add-ons/assist/getting-started.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.