> 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/reference/diagnostics.md). # Diagnostics & Data Storage This page covers Assist's connectivity diagnostics, log files, Developer mode tracing, troubleshooting environment variables, local file storage under `/assist/`, and how to uninstall or reset Assist. ## Connectivity diagnostics (`--diagnose`) To verify that external MCP clients can reach your open IDA session over the local Assist Mesh gateway, run the bundled `assist` bridge binary with `--diagnose`: * **macOS / Linux:** `~/.idapro/plugins/assist/bin/assist --diagnose` * **Windows:** `%APPDATA%\Hex-Rays\IDA Pro\plugins\assist\bin\assist.exe --diagnose` `--diagnose` checks the local gateway socket or named pipe, verifies authentication, and reports why a connection was refused (for example, no open IDA instance, a stale socket file, or an account/integrity-level mismatch). ## Environment variables | Variable | Purpose | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ASSIST_RAX_DISABLE=1` | Disables the embedded RAX emulator when set before starting IDA. Turns off both automatic per-function concrete micro-emulation and all `emulate*` tools while keeping static Hex-Rays microcode analysis active. | | `ASSIST_MCP_CONNECTION_CODE` | Temporary connection code passed to `assist --mcp --connect ` when connecting an external MCP client from another machine or VM through the opt-in **Network endpoint**. | | `ASSIST_HOME` | Overrides the Assist root directory (default: `/assist/`). | | `IDAUSR` | IDA's user directory path list; Assist uses its first entry when `ASSIST_HOME` is not set. | | `ASSIST_CONFIG_DIR` | Overrides the Assist configuration directory (`/config/`) used by the MCP bridge and mesh discovery. | | `ASSIST_OPENCODE_COMMAND` | Overrides the command line used to launch the **OpenCode** ACP subprocess (fallback: `ASSIST_ACP_COMMAND`; default: `opencode acp`). | ## Diagnostic logs and Developer mode Assist writes logs under `/assist/`: * **Always-on diagnostic log (`logs/assist_debug.log` and rotated `.1`).** Records general plugin diagnostics (as well as OpenCode ACP JSON-RPC wire traffic when OpenCode is used). Its redactor masks specific `Bearer` token and internal handles, not arbitrary binary or prompt text. * **Opt-in Developer session logs and timing profiles.** To capture detailed per-session traces, enable **Developer mode** under **Settings → Preferences… → Advanced**, which adds the **Developer** page to the settings sidebar. Under **Developer → Debug logging**, you can enable individual channels: * **External agent traffic** — Raw messages exchanged with Claude Code, OpenCode, and other external agents (`logs/sessions/.jsonl`). * **Built-in agent requests** — Full requests to the model API, returned items, token usage, and errors (`logs/sessions/.jsonl`). * **Agent turns and tools (Perfetto)** — Timing profiles for performance investigations (`profiles/native/*.json`; payloads omitted). * **Executed IDA scripts** — Every `idascript` Assist runs, with its success or failure status. * **Suggestion-engine diagnostics** — Why Assist refreshed, ranked, showed, or skipped suggested next actions. * **Tool calls and results only** — Narrows both agent logs to tool invocations and outputs, suppressing request payloads. *(When **External agent traffic** or **Built-in agent requests** is enabled without **Tool calls and results only**, session log files include prompts, tool payloads, and model responses.)* ## Where Assist stores data Assist stores all local state under `/assist/` (`~/.idapro/assist/` on macOS and Linux; `%APPDATA%\Hex-Rays\IDA Pro\assist\` on Windows): | Data | Location / mechanism | Protection | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **OpenAI-compatible API keys** | OS credential store (macOS Keychain, Windows Credential Manager, Linux Secret Service); if the OS credential store is present but locked or denied, Assist reports an error (offering **Retry** and **Repair permissions**) rather than silently writing a file. Fallback `config/providers/keys/.key` is used only when no native OS credential service is available | Native OS credential store; fallback key files use current-user [DPAPI](/add-ons/assist/reference/glossary.md#dpapi) + owner-only [SID](/add-ons/assist/reference/glossary.md#sid) [DACL](/add-ons/assist/reference/glossary.md#dacl) on Windows, or `0600` in a `0700` directory on macOS/Linux | | **Managed OAuth accounts** | `accounts/codex//auth.json` (**ChatGPT account**; `codex` is the internal provider directory name), `accounts/grok//auth.json` (**Grok**) *(existing CLI accounts use the CLI's own store)* | `0600` files inside `0700` directories on macOS/Linux; explicit current-user-only SID DACLs on Windows | | **Settings & provider profiles** | `config/settings.json`, `config/providers/profiles.json` | `0600` files inside `0700` directories on macOS/Linux; owner-only SID DACLs on Windows | | **Assist Mesh node key** | `config/mesh/node.key` | `0600` file in a `0700` directory on macOS/Linux; current-user [DPAPI](/add-ons/assist/reference/glossary.md#dpapi) encryption and owner-only [SID](/add-ons/assist/reference/glossary.md#sid) [DACL](/add-ons/assist/reference/glossary.md#dacl) on Windows | | **Local IPC sockets & pipes** | `config/mesh/sock/.sock` and `gateway.sock` (macOS/Linux) or `\\.\pipe\ida-assist-` (Windows) | `0600` Unix domain sockets in a `0700` directory with kernel peer-credential checks on macOS/Linux; Named Pipes with owner-only SID DACLs (remote clients rejected) on Windows; authenticated and encrypted with [AMTP](/add-ons/assist/reference/glossary.md#amtp) | | **Knowledge bases & transcripts** | `knowledgebases/`, `sessions/` | Directories restricted to the current user (`0700` on macOS/Linux; owner-only SID DACLs on Windows). Any process running under your own OS user account can still access these files | | **Extensions** | `extensions/` | Local extension packages and state managed under **Settings → Preferences… → Extensions** (`0700` on macOS/Linux; owner-only SID DACLs on Windows) | ## Uninstalling or resetting Assist * **Uninstall the plugin:** Run `hcli plugin uninstall hexrays/assist` (or, for a manual install, close IDA and remove `/plugins/assist/`). Uninstalling the plugin binary leaves your saved settings, transcripts, and knowledge bases intact under `/assist/`. * **Reset Assist to a clean state:** Close all running IDA instances and delete `/assist/` (`~/.idapro/assist/` on macOS and Linux; `%APPDATA%\Hex-Rays\IDA Pro\assist\` on Windows). This removes all saved settings, OAuth account tokens, mesh keys, diagnostic logs, conversation transcripts, and per-binary knowledge bases, and re-triggers the **Set up Assist** wizard on next launch. *(API keys stored in your OS credential store can be removed under **Settings → Preferences… → Agent** before resetting, or directly in macOS Keychain, Windows Credential Manager, or Linux Secret Service under service names beginning with `com.hex-rays.assist.providers.`)* --- # 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/reference/diagnostics.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.