# Claude Code Source: https://docs.debugai.io/agents/claude-code Add the DebugAI tools to Claude Code with one command, and a hook that checks every failed command against your project's memory. Claude Code gets the three DebugAI tools: `lookup_error`, `debug_error` and `report_outcome`. You need Node.js 18.14.1 or later. `node -v` prints your version. ### 1. Run setup ```bash npx -y @debugai/mcp setup ``` It signs you in through your browser with a short code (free account, 10 debugs a day, no card). Then it adds DebugAI to every MCP client it finds on this machine, Claude Code included, and finishes by running `doctor` to check the result. To change Claude Code's config and nothing else: ```bash npx -y @debugai/mcp login npx -y @debugai/mcp install --client=claude-code ``` Add `--dry-run` to the `install` line to print the change without writing anything. ### 2. Start a new session Start a new Claude Code session, or run `/mcp` in the one you have open to reconnect. ### 3. Check it works Run `npx -y @debugai/mcp doctor`. Under **MCP clients** you want this line: ```text ✓ Claude Code — debugai configured ``` Then hand Claude an error and ask for the lookup by name: ```text Use the debugai lookup_error tool on this error: TypeError: Cannot read properties of undefined (reading 'name') ``` `lookup_error` makes no model call and does not count against your daily limit, so this check is free. Claude calls `lookup_error` and gets back a line like `Not seen before in this project (shop). Call debug_error with the full error for an analysis.` The name in brackets is the folder of the repository Claude is working in. ## Make Claude reach for it When Claude Code connects, the server tells it what the tools are for. A rule in your project file makes the habit dependable. Add this to `CLAUDE.md`: ```text title="CLAUDE.md" When a command fails, call the debugai lookup_error tool first: it is instant and free. If it has no confirmed fix, call debug_error before attempting your own, and pass the command that reproduces the failure as reproCommand. After applying a fix, call report_outcome so the project's error memory stays accurate. ``` ## Check every failed command with the hook A rule still leaves the decision to Claude, and agents skip the failures that look obvious. Those are the ones that come back. The hook takes the decision away. After every Bash or PowerShell command that exits with an error, it looks the output up in this project's memory and puts what it finds beside the failure, before Claude reacts to it. No command installs the hook. Add it yourself to `~/.claude/settings.json` for every project, or to `.claude/settings.json` in one repository: ```json title="~/.claude/settings.json" { "hooks": { "PostToolUseFailure": [ { "matcher": "Bash|PowerShell", "hooks": [ { "type": "command", "command": "npx -y @debugai/mcp@latest hook", "timeout": 20 } ] } ] } } ``` Then run `/hooks` inside Claude Code to see it loaded. What to expect from it: - **Most of the time it says nothing.** It speaks only when memory holds a fix for this error (confirmed, unproven or anti-pattern) or a fix this project reported as failed. A miss, a timeout, no network or a command that printed nothing all produce no output. - **It never holds Claude up.** Every path exits 0, and it waits at most 5 seconds for its input and 8 for the lookup. The `20` in the config caps it even if the network hangs. - **It never asks you to sign in**, because a hook cannot answer a sign-in. It uses the key that `npx -y @debugai/mcp login` stored, and without one it stays silent. - **It is free.** A lookup is not a debug and does not count against your limit. - **What leaves your machine.** The failed command's output, up to 3,000 characters (the start and end when it is longer), and the project id, which is a hash of the repository path. The command line itself is not sent, and nothing is stored. - **Which project.** The git repository the command ran in. Outside a repository, the folder itself. Your home folder, the folders above it and the filesystem root are refused, and so is the Windows profile under WSL (`/mnt/c/Users/`). There the hook stays silent. `npx` resolves `@latest` on every run. On one Linux machine that measured 1.5 to 1.9 seconds warm and 6.7 seconds cold, before the lookup itself. A global install took about a third of a second on the same machine: ```bash npm i -g @debugai/mcp@latest ``` Then use `"command": "debugai-mcp hook"` in the config. A global install does not update itself, so run that command again when a new version ships. To watch each run of the hook, start Claude Code with `claude --debug`. ## Added it with claude mcp add before `claude mcp add` defaults to the local scope, which registers DebugAI for one directory. It then works in that folder and nowhere else, which looks a lot like DebugAI needing setup in every repository. `doctor` points it out: ```text ! Claude Code — debugai configured for ONE directory only ``` Run `npx -y @debugai/mcp install --client=claude-code`, which always writes the user scope. If you would rather use Claude Code's own command, give it the scope: ```bash claude mcp add --scope user debugai -- npx -y @debugai/mcp@latest ``` ## The config it writes `setup` adds one entry to the top-level `mcpServers` in `~/.claude.json`. On Windows, `~` is your user folder, `C:\Users\`. ```json title="~/.claude.json" { "mcpServers": { "debugai": { "command": "npx", "args": ["-y", "@debugai/mcp@latest"] } } } ``` - Your key is never written into this file. It lives in `~/.debugai/config.json` with `0600` permissions, and every MCP client on the machine reads it from there. - Before changing the file, `install` saves a copy beside it, named `.claude.json.debugai-backup-`. Every other setting in the file is kept. - If the file has comments, the rewrite drops them, and `install` warns you when it does. The backup keeps them. - `npx -y @debugai/mcp uninstall` takes the entry out of every client config again. ## Next - [Work with your agent](/guides/work-with-your-agent): the lookup, debug and report loop, and how to point an answer at the right project. - [MCP server troubleshooting](/troubleshooting/mcp): `doctor` output, sign-in from inside a chat, and the errors an agent can get back. # Claude Desktop Source: https://docs.debugai.io/agents/claude-desktop Add the DebugAI tools to the Claude Desktop app with one command, then tell it which project you mean. Claude Desktop gets the three DebugAI tools: `lookup_error`, `debug_error` and `report_outcome`. You need Node.js 18.14.1 or later. `node -v` prints your version. ### 1. Run setup ```bash npx -y @debugai/mcp setup ``` It signs you in through your browser with a short code (free account, 10 debugs a day, no card). Then it adds DebugAI to every MCP client it finds on this machine, Claude Desktop included, and finishes by running `doctor` to check the result. To change Claude Desktop's config and nothing else: ```bash npx -y @debugai/mcp login npx -y @debugai/mcp install --client=claude-desktop ``` Add `--dry-run` to the `install` line to print the change without writing anything. ### 2. Quit and reopen Claude Desktop Quit Claude Desktop completely, then open it again. Closing the window is not enough. ### 3. Check it works Run `npx -y @debugai/mcp doctor`. Under **MCP clients** you want this line: ```text ✓ Claude Desktop — debugai configured ``` Then hand Claude an error and ask for the lookup by name: ```text Use the debugai lookup_error tool on this error: TypeError: Cannot read properties of undefined (reading 'name') ``` `lookup_error` makes no model call and does not count against your daily limit, so this check is free. Claude calls `lookup_error` and gets an answer back from DebugAI, such as `Not seen before in this project (shop). Call debug_error with the full error for an analysis.` An answer that starts `DebugAI memory is off for this call` also means the connection works. The server just does not know your project yet, which the next section fixes. ## Tell it which project you mean An agent in a terminal, like Claude Code, usually runs inside your repository, and DebugAI takes the project from that folder. Claude Desktop is an app with no project folder of its own, so the server may not know which repository you mean. It reads files only inside a project, and it never treats your home folder, a folder above it or the filesystem root as one. When it has no project, the footer of a `debug_error` answer says so: ```text No local files read: there is no usable project root (none named, or only your home directory, a folder above it or the filesystem root, which are never one). Pass projectRoot to name the project. ``` Name the folder in your message, for example "the project is in /Users/you/shop", and Claude can pass it to the tools as `projectRoot`. An absolute path to a file inside the repository works too: the server takes the repository that file is in. With a project named, DebugAI reads the source files the stack trace names, and the error is filed under that project's memory. ## The config it writes `setup` adds one entry to `mcpServers` in `claude_desktop_config.json`, in Claude's folder under your system's app data: ```text ~/Library/Application Support/Claude/claude_desktop_config.json ``` ```text %APPDATA%\Claude\claude_desktop_config.json ``` ```text ~/.config/Claude/claude_desktop_config.json ``` Or under `$XDG_CONFIG_HOME` when that is set. ```json title="claude_desktop_config.json" { "mcpServers": { "debugai": { "command": "npx", "args": ["-y", "@debugai/mcp@latest"] } } } ``` - Your key is never written into this file. It lives in `~/.debugai/config.json` with `0600` permissions, and every MCP client on the machine reads it from there. - Before changing the file, `install` saves a copy beside it, named `claude_desktop_config.json.debugai-backup-`. Every other setting in the file is kept. - If the file has comments, the rewrite drops them, and `install` warns you when it does. The backup keeps them. - `npx -y @debugai/mcp uninstall` takes the entry out of every client config again. `setup` adds Claude Desktop only when it finds Claude's folder under your app data. If its output does not list Claude Desktop, run `npx -y @debugai/mcp install --client=claude-desktop`, which writes the file either way. ## Next - [Work with your agent](/guides/work-with-your-agent): the lookup, debug and report loop, and how to point an answer at the right project. - [MCP server troubleshooting](/troubleshooting/mcp): `doctor` output, sign-in from inside a chat, and the errors an agent can get back. # Cline Source: https://docs.debugai.io/agents/cline Add the DebugAI tools to Cline in VS Code with one command. Cline gets the three DebugAI tools: `lookup_error`, `debug_error` and `report_outcome`. You need Node.js 18.14.1 or later. `node -v` prints your version. `setup` knows where Cline keeps its MCP settings inside VS Code. Cline in another editor keeps them in that editor's own folder, which `setup` does not look in. There, add [the entry](#the-config-it-writes) to Cline's settings file by hand. ### 1. Run setup ```bash npx -y @debugai/mcp setup ``` It signs you in through your browser with a short code (free account, 10 debugs a day, no card). Then it adds DebugAI to every MCP client it finds on this machine, Cline included, and finishes by running `doctor` to check the result. To change Cline's config and nothing else: ```bash npx -y @debugai/mcp login npx -y @debugai/mcp install --client=cline ``` Add `--dry-run` to the `install` line to print the change without writing anything. ### 2. Open Cline's MCP servers Open the Cline panel and go to **MCP Servers**. Cline reconnects on its own, without a VS Code restart. ### 3. Check it works Run `npx -y @debugai/mcp doctor`. Under **MCP clients** you want this line: ```text ✓ Cline (VS Code) — debugai configured ``` Then hand Cline an error and ask for the lookup by name: ```text Use the debugai lookup_error tool on this error: TypeError: Cannot read properties of undefined (reading 'name') ``` `lookup_error` makes no model call and does not count against your daily limit, so this check is free. Cline calls `lookup_error` and gets back a line like `Not seen before in this project (shop). Call debug_error with the full error for an analysis.` The name in brackets is your project's folder. ## Cline and the DebugAI extension Cline and the [DebugAI extension](/quickstart/vscode) can run in the same VS Code. They are separate: Cline's agent uses the MCP server from this page, and the extension gives you the editor commands and fixes you apply as a diff. ## The config it writes `setup` adds one entry to `mcpServers` in Cline's settings file, inside VS Code's user folder: ```text ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json ``` ```text %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json ``` ```text ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json ``` Or under `$XDG_CONFIG_HOME` when that is set. ```json title="cline_mcp_settings.json" { "mcpServers": { "debugai": { "command": "npx", "args": ["-y", "@debugai/mcp@latest"] } } } ``` - Your key is never written into this file. It lives in `~/.debugai/config.json` with `0600` permissions, and every MCP client on the machine reads it from there. - Before changing the file, `install` saves a copy beside it, named `cline_mcp_settings.json.debugai-backup-`. Every other setting in the file is kept. - If the file has comments, the rewrite drops them, and `install` warns you when it does. The backup keeps them. - `npx -y @debugai/mcp uninstall` takes the entry out of every client config again. ## Next - [Work with your agent](/guides/work-with-your-agent): the lookup, debug and report loop, and how to point an answer at the right project. - [MCP server troubleshooting](/troubleshooting/mcp): `doctor` output, sign-in from inside a chat, and the errors an agent can get back. # Cursor Source: https://docs.debugai.io/agents/cursor Give Cursor's agent the DebugAI tools with one command, alongside or instead of the editor extension. Cursor's agent gets the three DebugAI tools: `lookup_error`, `debug_error` and `report_outcome`. You need Node.js 18.14.1 or later. `node -v` prints your version. ## Two ways into Cursor DebugAI reaches Cursor two ways, and you can have either or both: - **The extension**, installed from Open VSX, gives you the editor commands: **DebugAI: Analyze Error** in the editor, **DebugAI: Analyze Terminal Error** from a right-click in the terminal, indexing, and fixes you preview and apply as a diff. See [Cursor, Windsurf, VSCodium](/quickstart/cursor-windsurf-vscodium). - **The MCP server**, on this page, is for Cursor's agent. Its tool descriptions tell the agent to call DebugAI the moment something it ran fails. The extension does not write anything into Cursor's MCP config. The MCP server is added by the command below. ### 1. Run setup ```bash npx -y @debugai/mcp setup ``` It signs you in through your browser with a short code (free account, 10 debugs a day, no card). Then it adds DebugAI to every MCP client it finds on this machine, Cursor included, and finishes by running `doctor` to check the result. To change Cursor's config and nothing else: ```bash npx -y @debugai/mcp login npx -y @debugai/mcp install --client=cursor ``` Add `--dry-run` to the `install` line to print the change without writing anything. ### 2. Let Cursor pick it up Nothing to restart. Cursor reads the new entry on its own. Open **Settings**, then **MCP**, and look for a green dot beside **debugai**. ### 3. Check it works Run `npx -y @debugai/mcp doctor`. Under **MCP clients** you want this line: ```text ✓ Cursor — debugai configured ``` Then hand Cursor's agent an error and ask for the lookup by name: ```text Use the debugai lookup_error tool on this error: TypeError: Cannot read properties of undefined (reading 'name') ``` `lookup_error` makes no model call and does not count against your daily limit, so this check is free. The agent calls `lookup_error` and gets back a line like `Not seen before in this project (shop). Call debug_error with the full error for an analysis.` The name in brackets is your project's folder. ## Make the agent reach for it When Cursor connects, the server tells the agent what the tools are for. A rule makes the habit dependable. Add this to `.cursorrules` in your project, or to whichever rules file your setup reads: ```text title=".cursorrules" When a command fails, call the debugai lookup_error tool first: it is instant and free. If it has no confirmed fix, call debug_error before attempting your own, and pass the command that reproduces the failure as reproCommand. After applying a fix, call report_outcome so the project's error memory stays accurate. ``` ## The config it writes `setup` adds one entry to `mcpServers` in `~/.cursor/mcp.json`. On Windows, `~` is your user folder, `C:\Users\`. ```json title="~/.cursor/mcp.json" { "mcpServers": { "debugai": { "command": "npx", "args": ["-y", "@debugai/mcp@latest"] } } } ``` - Your key is never written into this file. It lives in `~/.debugai/config.json` with `0600` permissions, and every MCP client on the machine reads it from there. - Before changing the file, `install` saves a copy beside it, named `mcp.json.debugai-backup-`. Every other setting in the file is kept. - If the file has comments, the rewrite drops them, and `install` warns you when it does. The backup keeps them. - `npx -y @debugai/mcp uninstall` takes the entry out of every client config again. ## Next - [Work with your agent](/guides/work-with-your-agent): the lookup, debug and report loop, and how to point an answer at the right project. - [MCP server troubleshooting](/troubleshooting/mcp): `doctor` output, sign-in from inside a chat, and the errors an agent can get back. # Gemini CLI Source: https://docs.debugai.io/agents/gemini-cli Add the DebugAI tools to Gemini CLI with one command. Gemini CLI gets the three DebugAI tools: `lookup_error`, `debug_error` and `report_outcome`. You need Node.js 18.14.1 or later. `node -v` prints your version. ### 1. Run setup ```bash npx -y @debugai/mcp setup ``` It signs you in through your browser with a short code (free account, 10 debugs a day, no card). Then it adds DebugAI to every MCP client it finds on this machine, Gemini CLI included, and finishes by running `doctor` to check the result. To change Gemini CLI's config and nothing else: ```bash npx -y @debugai/mcp login npx -y @debugai/mcp install --client=gemini-cli ``` Add `--dry-run` to the `install` line to print the change without writing anything. ### 2. Restart the session Quit the Gemini CLI session you have open and start a new one. ### 3. Check it works Run `npx -y @debugai/mcp doctor`. Under **MCP clients** you want this line: ```text ✓ Gemini CLI — debugai configured ``` Then hand Gemini an error and ask for the lookup by name: ```text Use the debugai lookup_error tool on this error: TypeError: Cannot read properties of undefined (reading 'name') ``` `lookup_error` makes no model call and does not count against your daily limit, so this check is free. Gemini calls `lookup_error` and gets back a line like `Not seen before in this project (shop). Call debug_error with the full error for an analysis.` The name in brackets is your project's folder. ## Make the agent reach for it When Gemini CLI connects, the server tells it what the tools are for. A rule in whatever instructions file your agent reads makes the habit dependable: ```text When a command fails, call the debugai lookup_error tool first: it is instant and free. If it has no confirmed fix, call debug_error before attempting your own, and pass the command that reproduces the failure as reproCommand. After applying a fix, call report_outcome so the project's error memory stays accurate. ``` ## The config it writes `setup` adds one entry to `mcpServers` in `~/.gemini/settings.json`. On Windows, `~` is your user folder, `C:\Users\`. ```json title="~/.gemini/settings.json" { "mcpServers": { "debugai": { "command": "npx", "args": ["-y", "@debugai/mcp@latest"] } } } ``` - Your key is never written into this file. It lives in `~/.debugai/config.json` with `0600` permissions, and every MCP client on the machine reads it from there. - Before changing the file, `install` saves a copy beside it, named `settings.json.debugai-backup-`. Every other setting in the file is kept. - If the file has comments, the rewrite drops them, and `install` warns you when it does. The backup keeps them. - `npx -y @debugai/mcp uninstall` takes the entry out of every client config again. ## Next - [Work with your agent](/guides/work-with-your-agent): the lookup, debug and report loop, and how to point an answer at the right project. - [MCP server troubleshooting](/troubleshooting/mcp): `doctor` output, sign-in from inside a chat, and the errors an agent can get back. # Other MCP clients Source: https://docs.debugai.io/agents/other-clients Add DebugAI to any MCP client that runs local servers, with one sign-in and one config entry. Any MCP client that can start a local server over stdio can run DebugAI. `setup` writes the config for Claude Code, Claude Desktop, Cursor, Windsurf, Zed, Gemini CLI and Cline, and for VS Code when you ask. For any other client, sign in once and add the entry yourself. You need Node.js 18.14.1 or later. `node -v` prints your version. ### 1. Sign in once ```bash npx -y @debugai/mcp login ``` Your browser opens on a short code to confirm (free account, 10 debugs a day, no card). On a machine with no browser, `login` prints the address instead, and you open it on any device. When it is done: ```text ✓ Signed in as you@example.com (free tier). ``` The key is saved to `~/.debugai/config.json` with `0600` permissions. Every client on the machine that starts the server reads it from there, so you never paste it into a client config. For CI or a machine that cannot open the sign-in page, paste a key from the **Settings** tab of your [dashboard](https://debugai.io/dashboard?tab=settings&src=docs) instead: ```bash npx -y @debugai/mcp login --key dbg_your_key ``` ### 2. Add the entry The command is `npx` and the arguments are `-y` and `@debugai/mcp@latest`. Most clients list servers under `mcpServers` in a JSON file, like this: ```json { "mcpServers": { "debugai": { "command": "npx", "args": ["-y", "@debugai/mcp@latest"] } } } ``` Keep the `@latest`. Without a version, `npx` runs the first copy of the package it finds, and an old global install wins over the newest release. That has happened: one agent ran a whole session on a copy from July that sent no project, so project memory was off for every call. `doctor` warns about an entry with no version, for the clients it knows. ### 3. Restart the client and check it works Restart or reload the client so it starts the server. Then hand its agent an error and ask for the lookup by name: ```text Use the debugai lookup_error tool on this error: TypeError: Cannot read properties of undefined (reading 'name') ``` `lookup_error` makes no model call and does not count against your daily limit, so this check is free. The agent calls `lookup_error` and gets back a line like `Not seen before in this project (shop). Call debug_error with the full error for an analysis.` The name in brackets is your project's folder. Running `npx -y @debugai/mcp` yourself in a terminal prints one line, starting `[debugai-mcp]`, and then waits. That is correct: it is a stdio server, waiting for a client to speak first. To check the install instead, run `npx -y @debugai/mcp --help`. ## Keep the key out of client configs Setting `DEBUGAI_API_KEY` in a client's `env` block works, and it wins over the stored key. It is still the wrong place for it. Client configs get committed and pasted, and after you rotate your key, the old one in that file keeps outranking the new stored one, so the client keeps failing. `doctor` flags a key written in plain text in a known client's config. Use `login`, and leave `env` out of the entry. ## Environment variables | Variable | Default | What it does | | --- | --- | --- | | `DEBUGAI_API_KEY` | none | Your key. Wins over the key `login` stored. | | `DEBUGAI_API_BASE` | DebugAI production | The API the server talks to, for a staging or self-hosted setup. Falls back to `api_base` in the config file. | | `DEBUGAI_TIMEOUT_MS` | `150000` | The deadline for `debug_error`, in milliseconds. `lookup_error` waits 8 seconds and `report_outcome` 15, whatever this says. The hook ignores it. | | `DEBUGAI_CONFIG_PATH` | `~/.debugai/config.json` | A different config file. | If your client has its own timeout for tool calls, set it above 150 seconds, the server's own deadline for `debug_error`. Otherwise the client can give up on an answer the server is still waiting for. ## The remote server DebugAI also runs a remote server at `https://mcp.debugai.io/mcp`, with OAuth sign-in and nothing to install. Today it is the server behind the ChatGPT and Codex plugin: set those up from [ChatGPT and Codex](/quickstart/chatgpt-codex). It sees only the text an agent passes in and cannot read your files. For any other client, use the local server on this page, which reads the source files a stack trace names inside your project. ## Next - [Work with your agent](/guides/work-with-your-agent): the lookup, debug and report loop, and how to point an answer at the right project. - [MCP server troubleshooting](/troubleshooting/mcp): `doctor` output, sign-in from inside a chat, and the errors an agent can get back. # VS Code agent mode Source: https://docs.debugai.io/agents/vscode-agent-mode With the DebugAI extension installed, VS Code's agent mode already has the DebugAI tools. Nothing else to install. VS Code's agent mode can call MCP servers, and the [DebugAI extension](/quickstart/vscode) brings one with it. Once the extension is installed and signed in, it registers a server named **DebugAI** with the same three tools the npm package has: `lookup_error`, `debug_error` and `report_outcome`. You need VS Code 1.101 or later. You do not need Node.js for this one: the server runs on VS Code's own runtime. ### 1. Install the extension and sign in Follow steps 1 and 2 of the [VS Code quickstart](/quickstart/vscode). The server uses the key the extension stored when you signed in. If VS Code starts the server before you have signed in, it shows `DebugAI needs an API key to start the MCP server.` Press **Set API Key** and sign in from there. ### 2. Find DebugAI in the server list Open the Command Palette (Ctrl Shift P, or Cmd Shift P on a Mac) and run **MCP: List Servers**. **DebugAI** is in the list. ### 3. Check it works In agent mode, hand the agent an error and ask for the lookup by name: ```text Use the debugai lookup_error tool on this error: TypeError: Cannot read properties of undefined (reading 'name') ``` `lookup_error` makes no model call and does not count against your daily limit, so this check is free. The agent calls `lookup_error` and gets back a line like `Not seen before in this project (shop). Call debug_error with the full error for an analysis.` The name in brackets is the folder you have open in VS Code. ## How the bundled server differs It is the same protocol surface as `@debugai/mcp` on npm. A few things follow from living inside the extension: - **It answers for the first folder open in VS Code.** The agent's errors are filed under the same project as the ones you debug from the editor, so the agent and the DebugAI panel share one memory for that folder. Open a different folder and the extension updates the server to match. With no folder open, it reads no local files. - **`projectRoot` is for an error from somewhere else**, a folder that is not the one open in VS Code. A `filePath` does not pick the project here, as it does on the npm server. - **Sign-in happens in the extension**, not inside the chat. When the key is rejected, the server tells the agent to have you run **DebugAI: Set API Key** from the Command Palette. - **Its footer says so.** Each answer's footer carries `DebugAI MCP (VS Code)`, so you can tell which server replied. ## Without the extension To give VS Code's agent the tools without installing the extension, add the npm server: ```bash npx -y @debugai/mcp login npx -y @debugai/mcp install --client=vscode ``` Then run **MCP: List Servers** from the Command Palette to confirm it is there. This path needs Node.js 18.14.1 or later. `setup` skips VS Code on purpose. With the extension installed, `doctor` says so: ```text · VS Code (native MCP) — no entry here, which is right with the DebugAI extension installed ``` With the extension installed, a second entry in `mcp.json` makes every DebugAI tool show up twice. To take it back out: `npx -y @debugai/mcp install --client=vscode --remove`. The entry goes under `servers` in `mcp.json`, in VS Code's user folder: ```text ~/Library/Application Support/Code/User/mcp.json ``` ```text %APPDATA%\Code\User\mcp.json ``` ```text ~/.config/Code/User/mcp.json ``` Or under `$XDG_CONFIG_HOME` when that is set. ```json title="Code/User/mcp.json" { "servers": { "debugai": { "type": "stdio", "command": "npx", "args": ["-y", "@debugai/mcp@latest"] } } } ``` - Your key is never written into this file. It lives in `~/.debugai/config.json` with `0600` permissions. - Before changing the file, `install` saves a copy beside it, named `mcp.json.debugai-backup-`. Every other setting in the file is kept. - If the file has comments, the rewrite drops them, and `install` warns you when it does. The backup keeps them. ## Next - [Work with your agent](/guides/work-with-your-agent): the lookup, debug and report loop, and how to point an answer at the right project. - [MCP server troubleshooting](/troubleshooting/mcp): `doctor` output, sign-in from inside a chat, and the errors an agent can get back. # Windsurf Source: https://docs.debugai.io/agents/windsurf Give Windsurf's agent the DebugAI tools with one command, alongside or instead of the editor extension. Windsurf's agent gets the three DebugAI tools: `lookup_error`, `debug_error` and `report_outcome`. You need Node.js 18.14.1 or later. `node -v` prints your version. Windsurf can also run the DebugAI extension from Open VSX, for the editor commands and fixes you apply as a diff. That is a separate install, covered in [Cursor, Windsurf, VSCodium](/quickstart/cursor-windsurf-vscodium). This page is the MCP server for Windsurf's agent. ### 1. Run setup ```bash npx -y @debugai/mcp setup ``` It signs you in through your browser with a short code (free account, 10 debugs a day, no card). Then it adds DebugAI to every MCP client it finds on this machine, Windsurf included, and finishes by running `doctor` to check the result. To change Windsurf's config and nothing else: ```bash npx -y @debugai/mcp login npx -y @debugai/mcp install --client=windsurf ``` Add `--dry-run` to the `install` line to print the change without writing anything. ### 2. Refresh Windsurf's MCP list Open Windsurf, go to **Settings**, then **MCP**, and press refresh. ### 3. Check it works Run `npx -y @debugai/mcp doctor`. Under **MCP clients** you want this line: ```text ✓ Windsurf — debugai configured ``` Then hand Windsurf's agent an error and ask for the lookup by name: ```text Use the debugai lookup_error tool on this error: TypeError: Cannot read properties of undefined (reading 'name') ``` `lookup_error` makes no model call and does not count against your daily limit, so this check is free. The agent calls `lookup_error` and gets back a line like `Not seen before in this project (shop). Call debug_error with the full error for an analysis.` The name in brackets is your project's folder. ## Make the agent reach for it When Windsurf connects, the server tells the agent what the tools are for. A rule in whatever rules file your agent reads makes the habit dependable: ```text When a command fails, call the debugai lookup_error tool first: it is instant and free. If it has no confirmed fix, call debug_error before attempting your own, and pass the command that reproduces the failure as reproCommand. After applying a fix, call report_outcome so the project's error memory stays accurate. ``` ## The config it writes `setup` adds one entry to `mcpServers` in `~/.codeium/windsurf/mcp_config.json`. On Windows, `~` is your user folder, `C:\Users\`. ```json title="~/.codeium/windsurf/mcp_config.json" { "mcpServers": { "debugai": { "command": "npx", "args": ["-y", "@debugai/mcp@latest"] } } } ``` - Your key is never written into this file. It lives in `~/.debugai/config.json` with `0600` permissions, and every MCP client on the machine reads it from there. - Before changing the file, `install` saves a copy beside it, named `mcp_config.json.debugai-backup-`. Every other setting in the file is kept. - If the file has comments, the rewrite drops them, and `install` warns you when it does. The backup keeps them. - `npx -y @debugai/mcp uninstall` takes the entry out of every client config again. ## Next - [Work with your agent](/guides/work-with-your-agent): the lookup, debug and report loop, and how to point an answer at the right project. - [MCP server troubleshooting](/troubleshooting/mcp): `doctor` output, sign-in from inside a chat, and the errors an agent can get back. # Zed Source: https://docs.debugai.io/agents/zed Give Zed's agent the DebugAI tools with one command, or one entry in your Zed settings. Zed's agent gets the three DebugAI tools: `lookup_error`, `debug_error` and `report_outcome`. You need Node.js 18.14.1 or later. `node -v` prints your version. The entry goes into Zed's main `settings.json`. `install` keeps every setting in it but drops comments, because JSON has nowhere to put them. The backup it writes first still has them. Run `npx -y @debugai/mcp install --client=zed --dry-run` to see the change first, or paste the entry from [the config it writes](#the-config-it-writes) in by hand to keep your comments. ### 1. Run setup ```bash npx -y @debugai/mcp setup ``` It signs you in through your browser with a short code (free account, 10 debugs a day, no card). Then it adds DebugAI to every MCP client it finds on this machine, Zed included, and finishes by running `doctor` to check the result. To change Zed's config and nothing else: ```bash npx -y @debugai/mcp login npx -y @debugai/mcp install --client=zed ``` ### 2. Let Zed reload Nothing to restart. Zed reloads its settings when the file is saved, and **debugai** appears in the agent panel. ### 3. Check it works Run `npx -y @debugai/mcp doctor`. Under **MCP clients** you want this line: ```text ✓ Zed — debugai configured ``` Then hand Zed's agent an error and ask for the lookup by name: ```text Use the debugai lookup_error tool on this error: TypeError: Cannot read properties of undefined (reading 'name') ``` `lookup_error` makes no model call and does not count against your daily limit, so this check is free. The agent calls `lookup_error` and gets back a line like `Not seen before in this project (shop). Call debug_error with the full error for an analysis.` The name in brackets is your project's folder. ## The config it writes Zed takes a different key from the other clients, `context_servers`, and a nested command: ```text ~/.config/zed/settings.json ``` Or under `$XDG_CONFIG_HOME` when that is set. ```text ~/.config/zed/settings.json ``` Or under `$XDG_CONFIG_HOME` when that is set. ```text %APPDATA%\Zed\settings.json ``` ```json title="zed/settings.json" { "context_servers": { "debugai": { "source": "custom", "command": { "path": "npx", "args": ["-y", "@debugai/mcp@latest"] } } } } ``` - Your key is never written into this file. It lives in `~/.debugai/config.json` with `0600` permissions, and every MCP client on the machine reads it from there. If you add the entry by hand, run `npx -y @debugai/mcp login` once to store it. - Before changing the file, `install` saves a copy beside it, named `settings.json.debugai-backup-`. Every other setting in the file is kept. - `npx -y @debugai/mcp uninstall` takes the entry out of every client config again. ## Next - [Work with your agent](/guides/work-with-your-agent): the lookup, debug and report loop, and how to point an answer at the right project. - [MCP server troubleshooting](/troubleshooting/mcp): `doctor` output, sign-in from inside a chat, and the errors an agent can get back. # Error memory Source: https://docs.debugai.io/concepts/error-memory What DebugAI remembers about each error in a project, how a fix becomes remembered, and what makes it forget one. DebugAI remembers the errors each of your projects has hit, and what happened to the fixes. When the same error comes back, the answer starts from that history instead of from nothing. DebugAI recognises an error by its signature: the error with the values that change from run to run taken out. Memory belongs to your account. Nobody else sees it, teammates included. ## What the badges mean When memory has something on an error, the results panel shows one badge above the answer. Hover over it for the line in quotes. | Badge | What it says | | --- | --- | | **Fixed before · verified** | "A live session watched this error stop after the fix was applied." | | **Fixed before** | "A fix for this error was applied and accepted here before. Not observed to work." | | **A previous fix didn't hold** | "A fix was applied for this error before and the error came back. The analysis below has been told not to repeat it." | | **Seen before** | "This exact error has occurred in this project before." | A live session is [Debug in Browser](/guides/debug-in-browser) watching your running app, which is how DebugAI can see an error stop, not only be told it did. ## How a fix gets remembered A fix is remembered for an error when there is evidence it helped. From the extension: - Pressing **Apply** on a fix, or **Copy**, tells DebugAI that fix helped. - A thumbs up under the answer says the answer as a whole helped. - A thumbs down records what went wrong. It does not erase anything from memory: an opinion about an answer is not proof about your program. From an AI agent, `report_outcome` carries the verdict: | Result | When to use it | What memory does | | --- | --- | --- | | `worked` | A DebugAI fix was applied and the error stopped | Remembers the fix named in `fixRank` | | `worked_modified` | A fix worked only after changes | Remembers the code sent in `finalFix`, not the original suggestion | | `failed` | A fix was applied and did not help | Shows that fix to the project's analyses and lookups for the next week as one not to repeat | | `unused` | No DebugAI fix was applied, and it was solved another way | Counts nothing for or against any fix. The real fix, sent in `actualFix`, is logged | `unused` is not `failed`. A fix nobody ran is no evidence against it, and reporting it as failed would bury an answer that may have been right. A right diagnosis whose fix did not apply cleanly is `unused` too. ## How memory stops trusting a fix When an error comes back after its fix was remembered, memory counts it: - **Once:** the fix becomes unproven. A single return can be a stale browser tab or a hot reload replaying the old code, so memory says less rather than more: the badge reads **A previous fix didn't hold** and the answer is told the fix is unproven. - **Twice or more:** the fix is marked as one not to repeat. The next answer is told to avoid it. Memory keeps the failed fix rather than deleting it. "This was tried and it did not hold" stops the next answer from suggesting it again. ## Asking memory directly An agent can call `lookup_error` with an error. It answers from memory alone: no model call, nothing counted against your daily limit. It says whether the project has seen the error, how often, and which fix was confirmed for it or reported as failed. With the [Claude Code hook](/agents/claude-code), that lookup runs on every failed shell command. On your dashboard, **Still coming back** on the **Overview** tab lists the errors that keep recurring, with a **Yes** and **No** to tell DebugAI whether a fix held. ## What counts as one project Memory is kept per project, and each surface identifies a project in its own way: | Surface | The project is | | --- | --- | | VS Code extension | The first folder open in the workspace | | MCP server | The git repository it runs in, or its working folder when there is no repository. An agent can name another with `projectRoot` | | ChatGPT and Codex plugin | The project name in the tool call. Calls that name none share one project, called `chatgpt` | On macOS and Linux, the extension and the MCP server share one memory when the folder you open in the editor is the root of the git repository. On Windows they do not yet: they spell the same folder differently, so they keep two memories of one checkout. See [MCP server problems](/troubleshooting/mcp). ## Keeping and deleting it Debug history and error memory are kept with your account, with no fixed expiry, so the fixes that worked stay available. To have them deleted, email privacy@debugai.io from the address on your account. More in [What leaves your machine](/concepts/privacy). # How DebugAI works Source: https://docs.debugai.io/concepts/how-it-works What happens between an error on your screen and a fix in a diff, and what DebugAI does not do. DebugAI works in two halves. Before anything breaks, it indexes your project. When something breaks, it reads the error, finds the code that matters, and answers with a root cause and ranked fixes. ## Before an error: the index With the extension signed in, your project is indexed when VS Code starts and again for each file you open or save. The text of each source and config file is sent over HTTPS to DebugAI's servers, up to 50 KB a file and up to 500 files a run. The free plan keeps 200 files per project. On the server, each file is split into chunks. For Python, JavaScript and TypeScript the chunks follow the code's structure, and Java and C# files are indexed too. Voyage AI turns each chunk into an embedding, a list of numbers that places code with a similar meaning close together. The chunks and their embeddings are stored in your project index, under your account. The index is used only for your own debugs and is never shared with other users. This is what lets DebugAI find code a stack trace never names. A crash in `cart.py` can come from a value set in `settings.py`, and only the index knows `settings.py` exists. [Index your project](/guides/index-your-project) covers the details and the setting that turns automatic indexing off. ## When an error happens: one debug Nothing is analysed until you ask. The extension keeps the output of the last five terminal commands in memory, and reads it only when you run **DebugAI: Analyze Terminal Error**. From the editor, one debug goes like this: 1. You run **DebugAI: Analyze Error** (Ctrl Alt D) or **DebugAI: Analyze Terminal Error**. 2. The extension takes the error text and up to 30 lines of code either side of your cursor. Error text over 3,000 characters is cut, keeping its start and its end. 3. It adds a few facts about the project that the error cannot carry: the dependency names and versions your manifests declare, which kinds of manifest exist, the names of your Python modules, whether a virtual environment or `node_modules` is present, and the Python interpreter VS Code has selected. 4. All of it goes over HTTPS to the DebugAI API. 5. The engine embeds the error text with Voyage AI and searches your project index for the code related to it. 6. The error, your code and the related code go to Claude (Anthropic) for analysis. When Claude is unavailable, the same request goes to OpenAI's GPT-4o-mini. 7. Where a fix can be checked mechanically, it is, and each fix is labelled with the result. See [Verification](/concepts/verification). 8. The answer is cached for a short time, so the same request is answered without asking the model twice, then deleted. 9. You see a root cause and up to three ranked fixes. Nothing is written to a file until you open a fix as a diff and press **Apply**. If your project has met the same error before, the analysis is given that history, including any fix reported as failed in the last week, so it is not suggested again. That is [error memory](/concepts/error-memory). ## Which model answers | Plan | Model | | --- | --- | | Free | Claude Haiku 5.5 | | Pro and Team | Claude Haiku 5.5, with hard errors routed to Claude Sonnet 4.6 | | Any plan, when Claude is unavailable | OpenAI GPT-4o-mini | ## From an AI agent The MCP server follows the same path from the API on. What it sends is a little different, because it runs beside your agent instead of inside your editor: - It reads up to three source files the stack trace names, only inside the project, and sends the 40 lines either side of the failing line (a short file goes whole). A code snippet the agent passes replaces those reads. - It sends the same project facts, without the interpreter path, plus whether a `.env` file exists. It never opens one. - When the agent gives them, it sends the command that reproduces the failure and the output expected once it is fixed. DebugAI never runs that command. The DebugAI plugin for ChatGPT and Codex is different again. It sees only what each tool call passes in. It cannot read your files or run code, so paste the error and the code around it. See the [ChatGPT and Codex quickstart](/quickstart/chatgpt-codex). ## What DebugAI does not do - It does not do browser or end-to-end testing, and it does not write Playwright or Cypress tests. - It does not write tests or run your test suite. It debugs the error a failing test prints. - It does not open tunnels to localhost, review pull requests or monitor production. - It does not generate applications from scratch. - It does not change a file without showing you the change first and waiting for you to accept it. DebugAI works at development time, on errors that have already happened in your own project. # What leaves your machine Source: https://docs.debugai.io/concepts/privacy What each part of DebugAI sends, what it never sends, and where your key is kept. This page is a plain summary. The [privacy policy](https://debugai.io/privacy?src=docs) is the full statement and wins wherever the two differ. Both describe extension 2.12.1 and `@debugai/mcp` 2.7.0. Older versions sent more, and the policy lists what. ## Indexing While you are signed in, the extension indexes the project you have open: when VS Code starts, and again for each file you open or save. - **Sent:** the text of each source and config file in the workspace, up to 50 KB a file and up to 500 files a run. The free plan keeps 200 files per project. - **Where it goes:** over HTTPS to DebugAI's servers, which split it into chunks and send the chunks to Voyage AI to be embedded. The chunks and embeddings are stored in your project index, scoped to your account and never shared with other users. - **Never sent:** `.env` files and the like, key and certificate files, build and dependency folders, files outside the workspace, and your git history. - **To turn it off:** set `debugai.autoIndex` to off. Then nothing is indexed until you run an Index command or a scan. ## A debug from the editor - **Sent:** the error message, up to 30 lines of code either side of your cursor, and the full path of the file you are in. - **Also sent:** facts the error cannot carry. These are the dependency names and versions your manifest files declare, which kinds of manifest exist (not where), the names of your Python modules, whether a virtual environment or `node_modules` folder exists, and the path of the Python interpreter VS Code has selected. They are used to answer the request and not kept with your account. - **Where it goes:** the DebugAI API. Voyage AI embeds the error to search your project index, and Claude (Anthropic) analyses it, or OpenAI when Claude is unavailable. - **Never sent:** nothing about your git repository (no branch name, no changed file names, no diff), and no file contents beyond the code around your cursor. - **No code at all:** when the focused file looks like it holds credentials (an environment file, a key or certificate, `.npmrc`, `.netrc`, `.git-credentials`, anything under `.ssh` or `.aws`), or when the lines around your cursor hold a private key. The error text is still sent, and the status bar says the code was not. The answer is cached for a short time, then deleted. What DebugAI keeps from a debug is under [What is kept](#what-is-kept). ## A Proactive Scan A scan indexes the files it picks, even with `debugai.autoIndex` off, and sends their text to Claude (or OpenAI when Claude is unavailable) for review. It uses git only to choose files, and sends their paths, sizes and how recently they changed, never history, branch names or diffs. DebugAI keeps each finding's file, line and severity. ## Debug in Browser Debug in Browser (closed beta) sends a failed request's method, address, status, headers and bodies. Credential headers are removed first, and the bodies go through secret redaction. ## From an AI agent The standalone MCP server and the one built into the extension send: - The error text. - Up to three source files the stack trace names, read only inside the project, as the 40 lines either side of the failing line (a short file goes whole). A code snippet the agent passes replaces them. - The file path, and the same project facts as the editor, without the interpreter path. - Whether a `.env` file exists. Never its contents. - When the agent gives them, the command that reproduces the failure and the output expected once it is fixed. DebugAI never runs the command. The project is the folder or git repository the agent names, or else the folder VS Code has open (the extension's server) or the repository or folder the standalone server started in. Your home folder, the folders above it, the filesystem root, and the Windows profile as WSL shows it (`/mnt/c/Users/`) are never treated as a project. A project folder inside any of them is fine. ## From ChatGPT or Codex The DebugAI plugin receives only what each tool call carries: the error text, and for an analysis optionally a code snippet, a file name, a language and a project name, or your report on whether a fix worked. It never receives your conversation. Before a file name is used, your home folder is removed from it and only its last three parts are kept. Credentials DebugAI recognises in the error text are removed before it is analysed or stored. A code snippet is analysed as it was sent, so leave secrets out of it. ## Everything else - The extension asks DebugAI for your plan, usage and product notices (when VS Code starts, after each debug, and at most every 15 minutes), and reports counts of its own errors. None of that includes your code or file names. - While VS Code telemetry is on, the extension sends product events to PostHog, with no code and no file names. Turn VS Code telemetry off and it sends none. ## Where your key is kept | Surface | Where | | --- | --- | | VS Code, Cursor, Windsurf, VSCodium | VS Code's encrypted SecretStorage | | MCP server | `~/.debugai/config.json`, a file only you can read (mode 0600 on macOS and Linux) | | ChatGPT and Codex | No DebugAI key. ChatGPT or Codex holds a sign-in token for your account until you disconnect the plugin | Neither the extension nor `npx -y @debugai/mcp setup` writes your key into a client's config file. ## What is kept - **Your project index:** while it is active, until you ask for it to be deleted. - **Debug history and error memory:** the error text of each debug with credentials removed, the file you debugged and the files its stack trace names, the fixes offered, which one you applied and whether it worked. Kept with your account with no fixed expiry, so the fixes that worked stay available. See [Error memory](/concepts/error-memory). - **Short-term caches:** deleted on their own. To have your data deleted, email privacy@debugai.io from the address on your account. ## Who processes it | Service | What for | | --- | --- | | Anthropic | AI analysis | | OpenAI | AI analysis, only when Anthropic is unavailable. It receives the same request | | Voyage AI | Code embeddings | | Clerk | Sign-in | | Paddle | Payments, as merchant of record | | PostHog | Product analytics | | Sentry | Error monitoring of DebugAI itself, never your code | | Railway | Hosting for the API, engine and database | | Vercel | Website hosting | | Resend | Account, billing and product email | | Loops | The newsletter list | Regions and the rest of the detail are in the [privacy policy](https://debugai.io/privacy?src=docs#subprocessors). # Verification Source: https://docs.debugai.io/concepts/verification What Verified, Failed check and Not verified mean on a fix, what DebugAI can check, and why the third label exists. Every fix DebugAI offers carries a confidence figure and one of three labels. The label says whether anything tested that figure. | Label | What it means | Its confidence | | --- | --- | --- | | **✓ Verified** | A mechanical check ran on the fix and passed | As the model gave it. A pass confirms the figure and never raises it | | **✗ Failed check** | A mechanical check ran and the fix failed it. DebugAI disproved its own fix before showing it to you | Capped at 15% | | **Not verified** | Nothing checked this fix | The model's own estimate, untouched | Hover over a label in the results panel to see the reason behind it. ## What DebugAI can check The checks are deliberately narrow. Each one proves one thing and nothing more: - **Syntax errors** (`SyntaxError`, `IndentationError`). DebugAI checks that the code parses with the fix in place. A pass means the fix is valid code, not that it does what you want. - **Import errors** (`ImportError`, `ModuleNotFoundError`). DebugAI checks that the import the fix names matches the files it retrieved for this debug. A pass does not mean the package is installed, because DebugAI cannot see what is installed on your machine. Every other kind of error gets **Not verified**. So does a fix the checks could not finish, for example one whose code continues past its own lines and cannot be judged as a fragment. ## Why Not verified has its own label Without it, an unchecked fix at 85% and a checked fix at 85% would look the same. They are not the same claim. One is a number a model wrote; the other survived a test. **Not verified** keeps the two apart instead of folding the third case into the first, so you know which figures to lean on. A fix for a runtime error, such as a `TypeError` or a `KeyError`, is **Not verified**, because the checks cover only syntax and import errors. That is not a warning. It means you read the diff, apply it and run your code, as you would with a fix from a colleague. ## A fix that failed before When a fix for the same error was reported as failed in this project, DebugAI caps its confidence when it offers that change again, and an agent's answer says when it was reported and as which fix. That record is part of [error memory](/concepts/error-memory). ## In the answer an agent gets The MCP server prints one of these lines under each fix: ```text ✓ Verified — ✗ Failed mechanical check (confidence capped) — · Not verified — confidence is the model's own estimate; nothing checked this fix. ``` The same state is in the tool's structured output as `verified`: `true`, `false` or `null`, with the reason in `verification_reason`. The DebugAI plugin for ChatGPT and Codex calls the three states `passed`, `failed` and `not_checked`. An answer can also hand the agent a command to run after applying a fix. When the agent passed `reproCommand`, that command is the check, with the expected result if the agent gave one. DebugAI itself never runs it. Otherwise the answer may offer a syntax-level check command. Either way, `report_outcome` is how the result gets back to DebugAI. ## In Proactive Scan [Proactive Scan](/guides/proactive-scan) labels findings the same way: - **verified**: the claim was checked against your source. - **unverified**: DebugAI could not check the claim mechanically. - **lowered**: the finding's severity was lowered because the claim could not be verified. Claims that were checked and did not hold up never reach your screen. The results panel says how many were dropped, for example `3 possible issues were checked against your source and dropped because they did not hold up.` # Your first debug Source: https://docs.debugai.io/first-debug A three-file project with a planted bug, where the line that crashes is not the line that is wrong. Watch DebugAI trace it. Most bugs worth a debugger do not sit on the line that crashes. This one does not either. The traceback points at one file, and the mistake is in another file it never names. Setting it up takes three files and uses one of your 10 free debugs. Do the [VS Code quickstart](/quickstart/vscode) first, as far as signing in. If you use an agent instead, see [With an agent](#with-an-agent) below. Pick a language once and every step below follows it. ### 1. Create the project Make an empty folder called `first-bug` and open it in your editor with **File**, **Open Folder**. Add these three files: ```python title="settings.py" # Shop settings. In a real app these come from the environment. TAX_RATE = "0.08" FREE_SHIPPING_OVER = 50 ``` ```python title="cart.py" from settings import TAX_RATE, FREE_SHIPPING_OVER def subtotal(items): return sum(item["price"] * item["qty"] for item in items) def total(items): sub = subtotal(items) shipping = 0 if sub >= FREE_SHIPPING_OVER else 5 return round(sub * (1 + TAX_RATE) + shipping, 2) ``` ```python title="main.py" from cart import total items = [ {"name": "keyboard", "price": 49.0, "qty": 1}, {"name": "cable", "price": 6.5, "qty": 2}, ] print(f"Total: {total(items)}") ``` ```js title="data.js" // Users as they come back from the API, where ids are strings. module.exports.users = [ { id: "1", name: "Ada" }, { id: "2", name: "Linus" }, ]; ``` ```js title="users.js" const { users } = require("./data"); function findUser(id) { return users.find((user) => user.id === id); } module.exports = { findUser }; ``` ```js title="main.js" const { findUser } = require("./users"); const user = findUser(2); console.log(`Hello, ${user.name}`); ``` ### 2. Index it Run **DebugAI: Index Entire Workspace**. It should report **Indexed 3 files.** This is the step that matters here: the traceback in the next step never names the file with the mistake in it, so without the index DebugAI has no way to read it. ### 3. Run it In the editor's terminal: ```bash python main.py ``` ```text Traceback (most recent call last): File ".../first-bug/main.py", line 7, in print(f"Total: {total(items)}") ^^^^^^^^^^^^ File ".../first-bug/cart.py", line 11, in total return round(sub * (1 + TAX_RATE) + shipping, 2) ~~^~~~~~~~~~ TypeError: unsupported operand type(s) for +: 'int' and 'str' ``` On some systems the command is `python3`. ```bash node main.js ``` ```text .../first-bug/main.js:4 console.log(`Hello, ${user.name}`); ^ TypeError: Cannot read properties of undefined (reading 'name') at Object. (.../first-bug/main.js:4:28) ``` ### 4. Ask DebugAI Right-click inside the terminal, pick **DebugAI: Analyze Terminal Error**, then **Analyze This**. ### 5. Read the answer The crash is in `cart.py`, line 11. The cause is `settings.py`, line 2: `TAX_RATE` is the string `"0.08"`, not the number `0.08`. That is what the **Root Cause** should name. A fix that wraps `TAX_RATE` in `float()` inside `cart.py` would also stop the crash. It treats the symptom: every other file that imports `TAX_RATE` breaks the same way. A fix in `settings.py` treats the cause. The crash is in `main.js`, line 4, where `user` is `undefined`. The cause is two files away: `data.js` stores ids as strings (`"2"`), `main.js` asks for the number `2`, and `findUser` in `users.js` compares them with `===`, so nothing matches. The **Root Cause** should name that mismatch, not just the missing `user`. A fix that checks for `undefined` in `main.js` would stop the crash and still never find Linus. A fix where the ids are compared treats the cause. ### 6. Apply it and run again Press **Preview & Apply Fix** on the fix that treats the cause, check the diff, and press **Apply**. Then run the program again: ```text Total: 66.96 ``` ```text Hello, Linus ``` ## What just happened DebugAI read the traceback, then searched your index for the code behind it. That search is how an answer can reach a file the traceback never names. The fix you applied is recorded with the error, so if the same error comes back in this project, the panel says so with a **Fixed before** badge. See [Error memory](/concepts/error-memory). ## With an agent Open the `first-bug` folder in your agent ([setup](/quickstart/agents)) and ask: ```text Run python main.py. If it fails, use DebugAI to find the root cause before you change anything. ``` For JavaScript, ask it to run `node main.js` instead. The npm server has no index step: it reads the files the stack trace names, up to three, from inside the project. If the answer stops at the file that crashed, ask your agent to pass DebugAI the file the import comes from. In ChatGPT or Codex, paste the three files and the traceback, then ask it to debug with DebugAI. The plugin cannot read your files, so it only knows what you paste. ## Next - [Read a result](/guides/read-a-result): what each part of the panel means. - [Index your project](/guides/index-your-project), for your real code. # Apply and undo a fix Source: https://docs.debugai.io/guides/apply-and-undo Preview a fix as a diff, apply it to your file, and take it back if it was wrong. Nothing is written to your files until you have seen the diff and pressed **Apply**. If DebugAI cannot place a fix safely, it says why on the fix card and leaves the file alone. ### 1. Open the diff On a fix card, press **Preview & Apply Fix**. The button reads **Opening diff…**, then VS Code opens a diff titled **DebugAI: Review Fix #1 · cart.py** (the rank and the file name). Your file is on the left and the fixed version on the right. ### 2. Apply or cancel Back on the card it says `Review the diff above, then confirm or cancel.` Press **Apply** to write the change, or **Cancel** to leave the file as it is. When the change lands you get `Fix applied to cart.py. Review the change.` and the button reads **Applied**. ### 3. Undo, if you need to For 30 seconds after applying, the card shows `Fix applied.` with **Undo**. After that, Ctrl Z in the file still takes the change back: DebugAI writes through the editor, the way your own typing does. Then run the command that failed again. A fix is done when the error stops, not when the diff looks right. The command that failed now runs clean. If it fails with a new error, debug that one the same way. ## Where a fix goes DebugAI picks the file in this order, and refuses when none fits: 1. A fix that is an install command (`npm install`, `yarn add`, `pnpm add`, `bun add`) is not a file change. You are told to run it in your terminal. 2. If the answer names a file for the fix, that file, found in your workspace. 3. A one-line `pip install` of named packages becomes lines in `requirements.txt`. A fix written for `requirements.txt`, `.env` or `.gitignore` is added to the end of that file, and the file is created if your project has none. Lines already in the file are skipped. 4. `package.json`, `tsconfig.json` and `pyproject.toml` are edited only when the fix names the file and its code has that file's shape. 5. Otherwise, the file the error names. ## Making a file that does not exist When a fix belongs in a file your project does not have yet, such as `requirements.txt`, DebugAI asks first, in a dialog that shows every line: `DebugAI will create requirements.txt in your project root containing:`. Press **Create file**, and you get `Created requirements.txt with the fix.` ## When DebugAI will not apply a fix These appear on the fix card. In each case **Copy** still works, and the fix may still be right. | Message | What to do | |---|---| | `This fix is a command, not a change to a file. Run it in your terminal:` and the command | Run the command yourself. | | `This fix is for cart.py, which DebugAI could not find in this workspace. Open that file and use Copy.` | The file is outside the open folder, or named differently. Open it and paste the fix in. | | `This fix belongs in tsconfig.json, which this project does not have. Use Copy and create it yourself.` | Create the file, then paste. | | `The error does not name a file, so there is nothing safe to open a diff against. Use Copy and put the fix in yourself.` | Paste the fix where it belongs, or analyse again with the full stack trace. | | `DebugAI would not place this fix in cart.py. Nothing in that file matches what the fix changes, and appending it blindly is how a fix ends up in an unrelated file. Use Copy and put it where it belongs.` | The fix does not match the file as it is now. Place it by hand. | | `Applying this would leave cart.py with an unclosed block, so DebugAI stopped before writing it. The fix itself may still be right. Use Copy and place it by hand.` | Paste it and close the block yourself. | | `requirements.txt already has every line this fix adds.` | Nothing to add. The cause is elsewhere. | | `Could not create requirements.txt in your project root. Check the folder is writable, or create the file yourself and use Copy.` | Check folder permissions, or create the file. | | `DebugAI could not place this fix automatically. Use Copy and put it in yourself.` | Place it by hand. | ## If the file changed while you were reviewing Before writing, DebugAI reads the file again. If it is not what the diff was built from, nothing is written: ```text cart.py changed while you were reviewing, so DebugAI did not write over it. Nothing was lost. Run the fix again to rebuild it against the current file. ``` **Undo** has the same rule. If you edited the file after applying, it refuses rather than take your edits with it: ```text cart.py has been edited since the fix was applied, so DebugAI did not undo it. That would have taken your later edits with it. Use Ctrl+Z in the editor instead. ``` ## An error inside a library When an error only points into library code, such as a package under `node_modules` or `site-packages`, a fix cannot be applied there. The card says **This error is inside a library file**, the apply button becomes **Copy fix below** and stays disabled, and **Re-analyze error now →** runs **DebugAI: Analyze Terminal Error** again. Your own code that called the library is the place to change. Open that file and run **DebugAI: Analyze Error** from it. The demo from **DebugAI: Try Demo Analysis** shows the same note. Its example files are not on your machine, so its fixes cannot be applied. ## What applying tells DebugAI Applying a fix records it as helpful, and pressing **Copy** records that you copied it. Both go to your account as feedback on that answer, which is part of how [error memory](/concepts/error-memory) learns which fix held. After your third applied fix, DebugAI asks once whether you would leave a review, with **Leave a Review** and **Not Now**. ## Next - [Read a result](/guides/read-a-result), to judge a fix before applying it. - [Proactive Scan](/guides/proactive-scan) fixes follow their own preview and apply steps. # The dashboard Source: https://docs.debugai.io/guides/dashboard Find your usage, your key, your debug history and a direct line to the person who builds DebugAI on debugai.io. The dashboard lives at [debugai.io/dashboard](https://debugai.io/dashboard?src=docs). Sign in with the same account your editor or agent uses. It has six tabs: **Overview**, **Messages**, **History**, **Setup & Guide**, **Feedback** and **Settings**. To open one directly, add `?tab=` and its id to the address: `overview`, `messages`, `history`, `guide`, `feedback` or `settings`. For example, [debugai.io/dashboard?tab=messages](https://debugai.io/dashboard?tab=messages&src=docs). ## Overview Four figures: **Debugs this week**, **Recurring errors**, **Fixes holding**, and **Today** (used out of your daily limit) or **This month** on a monthly plan. Under them: - **Daily usage**, with how many remain and `resets midnight UTC`. On a monthly plan it reads **This month**, with how many included debugs are left and `soft cap, resets the 1st, UTC`. - **Proactive Scan**, with the scans used today, how many are left, and how many files each scan reads. - **Still coming back**: errors that keep returning in your projects, how many times each came back, and when it was last seen. Each says `fix confirmed`, `no fix yet`, or asks `did the fix hold?` with **Yes** and **No**. Your answer is saved with that error. How memory uses it: [Error memory](/concepts/error-memory). Before your first debug, the Overview shows **3 steps to your first fix** and a line that waits for it: `listening for your first debug…` ## Setup & Guide This is where you connect things. **Connect your editor automatically** opens your editor with your key already set. Pick your editor first: **VS Code**, **Cursor**, **Windsurf**, **VSCodium** or **Insiders**. Then press **Connect** and the editor's name. The extension has to be installed for this to work. If the editor does not open, the page offers **Install the extension →**, and the copy method below it. If the editor already has a different key, it asks before replacing it: `DebugAI: A different API key is already configured. Replace it?` **Connect an AI agent** gives you the one command that signs in and wires up every MCP client on your machine. Press **Copy command** and run it in a terminal: ```bash npx -y @debugai/mcp setup ``` Under it, **Enter it here →** opens the page for a sign-in code you are already holding. Per-client steps: [AI agents over MCP](/quickstart/agents). The tab also lists the four setup steps and shows your API key (see [Your key](#your-key)). ## Your key Your key starts with `dbg_` and is shown masked, with **Reveal** and **Copy**. You only need it for the manual route: in VS Code, run **DebugAI: Set API Key** and paste it. Signing in from the editor or with `npx -y @debugai/mcp setup` stores a key without you ever seeing it. Never paste it into a config file that gets committed, or anywhere public. To replace it, open **Settings** and press **Rotate key…**. The warning is exact: ```text Every connected editor and MCP client stops working until you reconnect them. The old key dies immediately. ``` Then reconnect each one: **DebugAI: Sign In** in your editor, and `npx -y @debugai/mcp login --force` for your agents. ## Messages Write here and it goes straight to the person who builds DebugAI. A real person reads these. Replies land in this tab and in your email. A message can be up to 4,000 characters. Press **Send**, or Ctrl Enter (Cmd Enter on a Mac). Unread replies show a red badge on the tab. Every tab also has a box at the bottom, **Something broken, missing, or annoying?**, that writes into the same thread. ## History Your past debug sessions. On the free plan the list shows the last 7 days, and says so at its end. Pro and Team keep the full history. ## Feedback Two choices: **Something broke** (a wrong answer, a crash, a fix that did not apply, a button that did nothing) and **Something's missing** (a language, an editor, a workflow). The thumbs-down **Other** choice in the results panel brings you here. ## Settings The **Plan** table shows your plan, your debugs a day or a month, when the counter resets (`midnight UTC`, or `1st of the month, UTC` on a monthly plan) and how long history is kept. Free plans link to **Pricing**. Paid plans link to **Manage billing**, where you can cancel. Settings also has the editor connect button, your key, and **Rotate key…**. ## Starting the Pro trial The trial lasts 14 days and needs no card. Start it from [debugai.io/upgrade](https://debugai.io/upgrade?src=docs) with **Try Pro free for 14 days**. Nothing enrolls you automatically. The dashboard shows an upgrade offer only once you have used 80% of your daily limit. Depending on your account, that offer is the founding rate, the trial or Pro. ## Next - [Plans and limits](/reference/limits). - [Sign-in and keys](/troubleshooting/sign-in), when a key stops working. # Debug an error Source: https://docs.debugai.io/guides/debug-an-error Send an error to DebugAI from the terminal, the editor or a pasted stack trace, and know exactly what goes with it. Nothing is analysed until you ask. DebugAI keeps the last few terminal outputs in memory so it can read them when you do, and it never sends one on its own. ## From the terminal Run the failing command in VS Code's integrated terminal. Then right-click inside the terminal and pick **DebugAI: Analyze Terminal Error**. It is also in the Command Palette, and on the **Analyze error from terminal** button in the results panel. DebugAI shows what it found, as `Found in terminal: "..."` with the first 120 characters, and offers **Analyze This**, **Paste My Own** and **Cancel**. Where it reads from, in order: 1. **VS Code's shell integration.** The extension keeps the output of the last 5 commands, up to 50,000 characters each, with each command's exit code. It prefers the most recent command that exited with a non-zero code and printed an error. 2. **The terminal's own text.** If shell integration has nothing, it selects everything in the terminal, copies it, and puts your clipboard back the way it was. It reads the terminal, not your selection, so selecting text in the terminal first changes nothing. To send exactly the text you chose, copy it and use **Paste My Own**, or use **DebugAI: Analyze Error** below. When there is nothing usable, it asks you to paste the error, and the prompt says why: - `No error found in the terminal, only a prompt or command output. Paste the error text:` - `The terminal had nothing to read. Run the command that fails, then try again, or paste the error text:` - `DebugAI could not read a terminal in this window. Paste the error text:` ## From the editor Select the error text and press Ctrl Alt D (Cmd Alt D on a Mac). That runs **DebugAI: Analyze Error**. The shortcut works while the editor has focus. The same command is on the editor's right-click menu and on the **DebugAI** item in the status bar. What it sends depends on what is under your cursor: - **A selection** longer than 5 characters that reads as an error is used as it is. - **No selection**, and the line under your cursor reads as an error: it asks `Use: "..."` with **Yes**, **Paste My Own** and **Use Terminal Error**. - **Anything else** opens a box to paste into: `Paste error from terminal, browser (Streamlit/Flask UI), or app console:` It works with no file open too, and goes straight to the paste box. Paste the whole stack trace, not the last line. The frames are what name the files DebugAI should read. ## A file outside a project If the file you are in is not inside an open folder, DebugAI says so once per window: `DebugAI is reading this file on its own. Open the containing folder and it can index your project, trace errors across files, and remember fixes for this codebase.` Press **Open Folder** to fix it. Without a folder there is no project to index or remember. ## Warnings in the Problems panel After an analysis, DebugAI marks up to three of the lines the error names with a warning, `[DebugAI] Root cause:` and the start of the answer. Only lines in files that are inside your workspace and open in an editor get one. Their quick fix, **Fix with DebugAI**, runs **DebugAI: Analyze Error** again. The marks are replaced by the next analysis. ## A failing test There is no test runner integration, and DebugAI does not run your tests. Run the test in the integrated terminal and use **DebugAI: Analyze Terminal Error**, or paste the output into **DebugAI: Analyze Error**. DebugAI reads test output for the files in it, including pytest's `FAILED tests/x.py::test_y` summary lines and the stack frames a JavaScript test runner prints, so a test failure is traced like any other error. ## What one debug sends One request to `POST /api/debug`, over HTTPS: - the error text, cut to 3,000 characters with the start and the end kept; - the code around your cursor, up to 30 lines on each side and 50,000 characters, with the line number it starts on; - the language, the path of the file you are in, and a framework hint read from your manifests; - project facts: dependency names and versions, which manifests exist, Python module names, whether a virtual environment or `node_modules` exists, and the selected Python interpreter path; - a project id, which is an md5 hash of your first workspace folder's path; - the extension's version. Nothing about your git repository goes with a debug. Indexed files are already on the server, so they are not sent again. More in [What leaves your machine](/concepts/privacy). Two guards hold back the code, and the error text is still sent. If the file you are in looks like it holds credentials, the status bar shows for 8 seconds: ```text DebugAI: the code around your cursor was not sent, because this file looks like it holds credentials. The error text was. ``` If the 61 lines around your cursor contain the first or last line of a private key: ```text DebugAI: the code around your cursor was not sent, because it contains a private key. The error text was. ``` ## While it runs A notification says `DebugAI analyzing your error…` or `DebugAI analyzing terminal error…`, and the status bar shows **DebugAI analyzing...**. The extension waits up to 110 seconds for an answer. Past that you get `DebugAI: The engine did not answer within 110 seconds. It may be busy.` with **Retry**. Before you sign in, the editor command answers `DebugAI: not connected yet. Sign in for 10 free debugs a day, no card.` with **Sign in →** and **I Have a Key**, and the terminal command answers `DebugAI: No API key set.` with **Set API Key**. ## Text that is not an error Send a terminal prompt, a block of source code, or a DebugAI answer, and DebugAI says so instead of inventing a diagnosis. The root cause is one line, for example `That is a terminal prompt, not an error message.`, `That is source code, not an error.` or `No error message was found in that text.`, and the only fix is **Paste the error itself**, at 0%. That attempt is not counted against your daily limit. Sending the same text again gets the same answer, so change what you paste instead of retrying. ## Next - [Read a result](/guides/read-a-result): what each part of the panel tells you. - [Apply and undo a fix](/guides/apply-and-undo). - The answer says `Insufficient context for specific fix`: see [Read a result](/guides/read-a-result#insufficient-context) and [Index your project](/guides/index-your-project). # Debug in Browser Source: https://docs.debugai.io/guides/debug-in-browser Catch the errors your terminal never shows, from a frontend running in a browser that VS Code launches, and debug them where they happen. Debug in Browser is on only for accounts with beta access. Without it, both browser commands answer with `Debug in Browser is in closed beta. It catches browser-side failures your terminal never shows: silent exceptions, swallowed 4xx and 5xx. Everything else in DebugAI works as normal.` and a **Request access** button. You can also [request access here](https://debugai.io/beta?src=docs). It launches your frontend in Chrome or Edge under VS Code's JavaScript debugger and watches for what the terminal never prints: uncaught exceptions, unhandled promise rejections, `console.error` calls, and network requests that fail. A small **watching** badge sits in the page while it runs. ### 1. Start your dev server Open your project folder, then start the dev server as you normally do. Without a folder open, the command answers `DebugAI: Open your project folder first.` ### 2. Run Debug in Browser Run **DebugAI: Debug in Browser**. It takes your dev server's address from your terminal output, your running tasks, or the address you used last in this workspace. When it can only guess from your `package.json`, or finds nothing, it asks `Which URL is your dev server on?`, filled in with its guess or `http://localhost:3000`. It only launches local dev servers. Anything else is refused with `DebugAI only launches local dev servers.`, and a value that is not a full address with `Enter a full URL, e.g. http://localhost:5173`. If nothing answers at that address you get `DebugAI: nothing is answering at http://localhost:3000. Start your dev server, then try again.` with **Launch anyway** and **Use a different URL**. The browser opens as a debug session named **DebugAI Browser Session**. If none can start, the message asks `Is a Chrome or Edge build installed?` ### 3. Debug what it catches When something fails, a notification offers to debug it: - one error: `DebugAI caught:` and where it happened, with **Find root cause** and **Ignore**; - a failed request: what failed and the file and line that sent it, with **Debug this** and **Ignore**; - several at once: `DebugAI caught N browser errors. Review?` with **Review** and **Ignore**. Each runs as a normal debug and uses one of your debugs. The answer opens in the usual results panel. The status bar shows **DebugAI: watching**, and the page you opened has the watching badge. ## Everything it caught **DebugAI: Show Browser Captures**, or a click on the **DebugAI: watching** status bar item, lists what this session caught under `DebugAI: caught in this browser session`. Pick one to find its root cause. An error with no source location warns that the answer will be generic, because there is no code to read, and offers **Analyse anyway**. Before anything is caught it says `DebugAI: nothing caught in this browser session yet.` It also watches Chrome and Edge debug sessions you start yourself from VS Code. ## Console only If the network watch could not attach, you are told `DebugAI is watching console errors but not network requests. Failed requests will not be caught this session.` and the status bar reads **DebugAI: watching console only**. Exceptions and `console.error` are still caught. ## What it sends For a failed request: the method, the URL, the status, and the headers and bodies, with credential headers removed and bodies redacted first. For an exception: the error and where it happened, like any debug. More in [What leaves your machine](/concepts/privacy). # Index your project Source: https://docs.debugai.io/guides/index-your-project Let DebugAI read your project once, so an answer can name the file that broke and not only the file that crashed. An error points at the line that crashed. The line that is wrong is often somewhere else: a setting, a helper, the code that built the bad value. The index is how DebugAI reads those files. Without one, it sees the error and the code around your cursor, and an answer about another file is a guess. ## Start the first index yourself Signing in does not start an index. The **DebugAI connected** message that appears after sign-in has an **Index workspace** button: press it. If the message is gone, open the Command Palette (Ctrl Shift P, or Cmd Shift P on a Mac) and run **DebugAI: Index Entire Workspace**. Skip both and the first index waits until VS Code next starts. While it runs, the status bar shows **DebugAI indexing...** with a percentage, and the count of files sent so far. When it ends, a message says what the server stored (see [When it finishes](#when-it-finishes)). The closing message starts with `Indexed` and a number, and **DebugAI: Check Index Status** answers `DebugAI: N files indexed. Ready for errors.` ## After that it runs on its own While the `debugai.autoIndex` setting is on, which it is by default, DebugAI indexes: - the whole project once, each time VS Code starts with you signed in; - each file again when you open or save it, if the file is inside your workspace. An automatic full index is skipped when one finished for this project in the last 15 minutes. Running **DebugAI: Index Entire Workspace** yourself always runs. The first automatic index shows this notice once per install, with **Turn off auto-index** and **Privacy policy** buttons: ```text DebugAI is indexing this project so answers can point at the right files. It sends the text of your source and config files to DebugAI's servers, up to 50 KB each and up to 500 files per run on any plan (Free keeps 200), and files you open or save are sent again. .env files and key files are never sent. You can turn this off with the debugai.autoIndex setting. ``` ## Turn automatic indexing off Press **Turn off auto-index** on that notice, or set `debugai.autoIndex` to `false` in Settings. Nothing is indexed after that unless you ask: **DebugAI: Index Entire Workspace**, **DebugAI: Index Current File**, or a [Proactive Scan](/guides/proactive-scan), which indexes the files it picks whatever the setting says. ## When it finishes The message only counts what the server confirmed it stored. | Message | What it means | |---|---| | `Indexed N files. DebugAI can now trace an error across your codebase.` | Done. Every file found was stored. | | `DebugAI indexed N files so far. The remaining M are queued for the next run in about 15 minutes. Debugging works now; answers get better once the rest lands.` | The server asked DebugAI to slow down partway. Press **Finish indexing** later, or let the next automatic run pick them up. | | `DebugAI indexed N files. M more in this project were not indexed, so answers that need them will be incomplete. Nothing failed and there is nothing to retry.` | The plan's file cap was reached. The free plan keeps 200 files per project. | | `DebugAI: indexed N files. M could not be indexed and were not checked. Run indexing again to retry them.` | Some files failed on the way. Run **DebugAI: Index Entire Workspace** again. | | `DebugAI: The server asked us to slow down before anything was stored. Nothing was indexed. Try again in about 15 minutes.` | Rate limited before the first file was stored. Run it again later. | | `DebugAI: No files could be indexed. This is not a result about your codebase.` | Every file failed, so nothing was stored. Press **Try again**. | | `DebugAI: No files were indexed.` | Nothing was stored, for no reason the server named. | Two more come only from the command, when it had nothing to send: - `DebugAI found no files to index in this workspace. It indexes source files such as .py, .ts, .js, .java and .cs, and leaves out folders like node_modules and dist.` - `DebugAI could not search this workspace for files, so nothing was indexed. Run "DebugAI: Index Entire Workspace" to try again.` With no folder open, the command does nothing at all. Open your project folder first (**File**, **Open Folder**). Before you sign in, it answers `DebugAI: Set your API key first.` **View Details** on the closing message opens the **DebugAI Indexing** output panel: the count, a note on any files left out or queued, and every stored file under `Files indexed:`. ## The welcome panel The first index of a project opens a panel headed **DebugAI has read your codebase**. It lists up to eight of the files it stored, says how many could not be indexed this run if any, and offers a [Proactive Scan](/guides/proactive-scan) of them under **Try it on your own code** (**Scan my code** or **Not now**). It opens once per project. It does not open when nothing was stored or no folder is open, and the `debugai.showWelcome` setting turns it off. ## Index one file **DebugAI: Index Current File** sends the file in the active editor. It answers with one of: - `DebugAI: File indexed.` - `DebugAI: this file is queued and will index on the next run, in about 15 minutes.` - `DebugAI: could not index this file.` - `DebugAI: this file was not indexed. Secret files are never indexed, and free plans cap the project at 200 files.` With no file open in an editor, it does nothing. ## Check what is indexed **DebugAI: Check Index Status** answers with one of: - `DebugAI: N files indexed. Ready for errors.` - `DebugAI: Indexing in progress (n/t files, p%)...` - `DebugAI has not indexed this workspace in this window yet. Run "DebugAI: Index Entire Workspace" to index it now.` - `DebugAI: Set your API key to start indexing. Run "DebugAI: Set API Key" from the command palette.` - `DebugAI: No workspace open. Open a folder to begin indexing.` It reports on this VS Code window. An index from an earlier session is still on the server, so "not indexed in this window yet" does not mean your project has never been indexed. ## What is indexed - Source files ending in `.js` `.jsx` `.ts` `.tsx` `.py` `.mjs` `.cjs` `.java` `.cs`. - Config files with these exact names: `Dockerfile`, `Makefile`, `package.json`, `tsconfig.json`, `jsconfig.json`, `pyproject.toml`, `requirements.txt`, `setup.cfg`, `Pipfile`, `pom.xml`, `build.gradle`, `build.gradle.kts`, `settings.gradle`, `go.mod`, `cargo.toml`, `nginx.conf`, `firebase.json`, `vercel.json`, `netlify.toml`, `railway.json`. - Any `*.csproj` file, and `Dockerfile.*` variants such as `Dockerfile.prod`. - A file you open or save that VS Code treats as JavaScript, TypeScript, Python, JavaScript React or TypeScript React, whatever its extension, unless its name is on the list below. ## What is never indexed - The `.env` family: `.env`, `.env.local`, `staging.env`, `env.production`. A module named env, such as `env.ts` or `env.py`, is source and is indexed. - Key and certificate files: `.pem` `.key` `.pfx` `.p12` `.jks` `.keystore` `.ppk` `.asc` `.gpg` `.kdbx` `.crt` `.cer` `.der` `.cert` `.secret`. - Files whose whole name before the extension is a credential store word: `secret`, `secrets`, `credential`, `credentials`, `password`, `passwords`, `passwd`, `pwd`, `serviceaccount`, `service_account`, `service-account`. So `secrets.py` is left out and `reset_password.py` is not. - `appsettings*.json`, `docker-compose.yml` and `compose.yml`, lock files (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, anything ending in `.lock`), minified `.min.js` and `.min.css`, and `.map` files. - Anything inside these folders: `node_modules`, `dist`, `build`, `out`, `.git`, `__pycache__`, `.venv`, `venv`, `.env`, `.next`, `coverage`, `site-packages`, `.tox`, `env`, `.pytest_cache`, `eggs`, `.eggs`, `.ssh`, `.gnupg`, `.aws`, `.azure`, `.kube`, `.docker`, `secrets`, `.secrets`, `.nuxt`, `.terraform`, `dist-packages`. Folders are judged from inside your workspace folder, so a project that itself sits in a folder called `build` still indexes. ## Limits - Each file is cut at 50 KB. - One run looks at up to 4,000 matching files and sends at most 500. When there are more, the choice is the same every time: a tenth of the places are kept for config files, source comes before config, and tests, snapshots and vendored files rank below the rest. - The free plan keeps 200 files per project. Pro and Team have no file cap. - The server takes 600 index requests per 15 minutes per account. Files go up 10 at a time, and a run stops after three batches in a row where every file was turned away. What it did not send is queued for the next run. ## What leaves your machine The text of each indexed file goes to DebugAI's servers over HTTPS, where it is split into chunks, embedded with Voyage AI and stored under your account for your own debugs. Other users cannot see it. Details in [What leaves your machine](/concepts/privacy). ## Next - [Debug an error](/guides/debug-an-error), now that DebugAI can read your project. - Indexing went wrong: [Indexing troubleshooting](/troubleshooting/indexing). # Proactive Scan Source: https://docs.debugai.io/guides/proactive-scan Have DebugAI read the files you are working on and report defects it can prove against your source, before they turn into errors. A debug starts from an error you already hit. A scan starts from your code: DebugAI reads the files you changed and reports the defects it can prove against your actual source. Each claim is checked before it reaches you. Ones that do not hold up are dropped, and ones that cannot be checked say so. Scans have their own daily allowance and do not use your debugs. ### 1. Run a scan Open the Command Palette and run **DebugAI: Scan Workspace (Proactive)**. After a project's first index, the welcome panel offers the same thing as **Scan my code**. A notification titled **DebugAI · Proactive Scan** shows `Indexing N file(s)…`, then `Scanning N file(s)…`. The files are indexed first even when `debugai.autoIndex` is off, so the scan reads what is in them now. ### 2. Read what it found With findings, a panel opens beside your code, titled **DebugAI · Proactive Scan**. Its header counts the findings, how many are verified, the files read and the cached answers, for example `2 finding(s) · 1 verified · 3 file(s)`. Findings are grouped by file, verified ones first, then by severity. Each shows: - its severity: **high**, **medium** or **low**, plus **lowered** when the severity was reduced because the claim could not be verified; - the issue, in one line; - **verified** (hover it to see what checked it) or **unverified** (hover it for why it could not be checked); - the line it is about. Click it to open the file there; - the explanation. ### 3. Apply a fix A finding offers one of: - **Preview & apply fix**: DebugAI located the edit, applied it to a copy of your file and parsed the result cleanly. - **Preview fix**: the edit is located, but nothing could parse the result. Today that means TypeScript. - The suggested code with the note `This one needs a change we could not express as a single edit.` Copy it and place it yourself. Pressing either preview button opens a diff titled **Proposed fix · cart.py**, then asks `Apply this fix to cart.py?`. Press **Apply Fix** to write it, or cancel. A finding you cancel is treated as dismissed: later scans of this project hide it. The panel lists at least one finding with a clickable line, or a notification says `DebugAI: no issues found in N files.` with a real number of files. ## Which files it reads 1. Files with uncommitted git changes, in any repository in your workspace. 2. With none, files from your recent commits, starting with the last 30 and stepping down to 10, 5 and 1. 3. Without git, the files you modified most recently. The file in your active editor is always added. It takes up to 10 files ending in `.js` `.jsx` `.ts` `.tsx` `.py` `.mjs` or `.cjs`, and the welcome panel's scan offers up to 18. Only files in this workspace count, so a file open from somewhere else is not scanned. How many the server reads depends on your plan: | Plan | Scans a day | Files per scan | |---|---|---| | Free | 3 | 3 | | Beta | 5 | 10 | | Pro | 22 | 10 | | Team | 52 | 10 | The count resets at 00:00 UTC. A project's first scan may read up to 18 files, and stops after 3 findings. ## When it finds nothing You get a notification instead of a panel. "No issues" is only said about files that were actually read: - `DebugAI: no issues found in N files.` - `DebugAI: no issues found in N files. M could not be scanned and were not checked.` - `DebugAI: no issues found in N files. The scan hit its time limit, so the rest were not checked.` - `DebugAI: nothing new in N files. K findings you already dismissed are still there and hidden.` - `DebugAI: the scan examined no files. This is not a result about your code.` When the server gave the attempt back, the message ends `It was not counted against your limit.` The panel adds its own notes when they apply: `The scan hit its time limit, so some files were not read. These are partial results.`, `N file(s) could not be read this run. They were not judged either way.`, and how many possible issues were checked against your source and dropped. ## When it will not run | Message | What to do | |---|---| | `DebugAI: Set your API key first.` | [Sign in](/quickstart/vscode). | | `DebugAI: Open a folder to scan.` | Open your project folder. | | `DebugAI: nothing to scan. Open a file or make some changes first.` | Open a file from the project, or change one. | | `DebugAI: nothing to scan in this workspace. The file in front of you is outside it, and a scan reads this project's files. Open one of them, or open that file's folder.` | The file you have open is not in this workspace. | | `DebugAI: Daily scan limit reached` | Wait for 00:00 UTC, or press **Upgrade**. | | `DebugAI: Scan failed` with a status code, then `Try again.` | Run it again. If it keeps failing, write to support with the code. | A scan gives up after 120 seconds. ## When a scan fix will not apply - `DebugAI: this file has changed since the scan, so the fix no longer lines up. Run the scan again.` - `DebugAI: this fix points at a file that was not part of the scan, so it was not opened. Run the scan again.` - `DebugAI: nothing safe to change here. Copy the fix and place it yourself.` - `DebugAI: this finding has no one-click fix. The suggestion is in the panel.` - `DebugAI: this finding is from an earlier scan and is no longer on screen. Run the scan again.` Each one leaves your file as it was. ## What leaves your machine The files a scan picks are indexed, so their text goes to DebugAI's servers, and the scan sends that text to Claude (Anthropic), or to OpenAI when Claude is unavailable. It does this even with automatic indexing off. Details in [What leaves your machine](/concepts/privacy). ## Next - [Apply and undo a fix](/guides/apply-and-undo), for fixes from a debug. - [Plans and limits](/reference/limits). # Read a result Source: https://docs.debugai.io/guides/read-a-result Know what each part of the results panel means, how far to trust a fix, and what to do when an answer comes back empty. The panel answers two things: what broke, and what to change. Every fix also says how much of it was checked, so you can tell a tested answer from a confident guess. ## The parts of the panel The answer opens in a **DebugAI** tab beside your code, headed **DebugAI Results**. - **Root Cause** is the explanation, in plain language. - A row of badges says where the answer came from (see [Badges](#badges)). - **Ranked Fixes** lists up to three fixes, the most likely first. - **Was this helpful?** sends DebugAI your verdict (see [Tell DebugAI how it went](#tell-debugai-how-it-went)). - The last line counts what your plan has left: `9 AI debugs remaining today`, or on a monthly plan `120 of 1000 debugs used this month`. - **Session History**, on the left, lists your recent analyses. ## Each fix A fix card shows: - its rank and title; - where it applies, as plain text such as `cart.py:11` (not a link), and `in settings.py` when the fix belongs in a different file from the one in the error; - a confidence figure with a bar: green at 80% and above, amber from 60%, red below 60%; - one of three verification labels; - why this fix, then the code; - **Preview & Apply Fix** and **Copy**. See [Apply and undo a fix](/guides/apply-and-undo). `No fixes available.` means the answer came back with no fix to offer. ## The three labels Hover a label to see the reason DebugAI gives for it. | Label | Means | |---|---| | **✓ Verified** | A mechanical check ran on this fix and passed. The tooltip names the check, or says `Mechanical check passed`. | | **✗ Failed check** | DebugAI disproved its own fix before showing it to you, and capped its confidence. The tooltip says what failed. | | **Not verified** | Nothing checked this fix. The tooltip says `Not checked mechanically. The % is the model's own estimate.` and gives the reason when there is one. | A high percentage on a **Not verified** fix is the model's opinion of itself. Read the diff before you apply it. More in [Verification](/concepts/verification). ## Badges The first badge is about this error's history in your project, when it has one: | Badge | Means | |---|---| | **Fixed before · verified** | A live session watched this error stop after the fix was applied. | | **Fixed before** | A fix for this error was applied and accepted here before. Not observed to work. | | **A previous fix didn't hold** | A fix was applied for this error before and the error came back. The analysis below has been told not to repeat it. | | **Seen before** | This exact error has occurred in this project before. | Then, when they apply: - **Cached**: the answer came from DebugAI's store of recent answers to the same request. - **12 files** (or another number): the answer drew on that many files from your project index. No badge means no indexed file was used. - **high confidence**, **medium confidence** or **low confidence**: the analysis's overall confidence. - A framework name, such as **fastapi** or **nextjs**, when one was detected. - **Fast** or **Full**: which model answered. Fast means a Haiku model. Full means any other: Sonnet, which Pro and Team get on hard errors, or the fallback model DebugAI uses when Claude is unavailable. - The name of a known error pattern, when the error matched one. How memory works, and how a fix earns "verified": [Error memory](/concepts/error-memory). ## Session History The last 20 analyses stay in the panel's sidebar, newest first, and survive a restart. Click one to open it again. The footer shows your extension version. ## Tell DebugAI how it went Thumbs up records the answer as helpful. Thumbs down asks `What went wrong? (helps us improve)` and offers **Wrong fix**, **Wrong file**, **Off-target error**, **Too generic** and **Other**. **Other** opens the Feedback tab on your dashboard, where you can say more. Applying a fix records it as helpful by itself, and the thumbs lock for that answer. Copying a fix is recorded too. ## When the analysis fails The reason comes as a notification. If a results panel is already open, a card with the same sentence takes the place of the old answer. Its second button is always **Analyze error from terminal**. | Heading | What happened | Button | |---|---|---| | **The engine timed out** | No answer within 110 seconds. | **Try again** | | **Cannot reach DebugAI** | No connection to DebugAI's servers, or a firewall in the way. | **Try again** | | **Your key was rejected** | The key is invalid or expired. | **Update key** | | **Daily limit reached** | The free plan's daily debugs are used. They reset at 00:00 UTC. | **See plans** | | **Monthly ceiling reached** | A paid account passed its monthly usage ceiling. | **Open dashboard** | | **Slow down for a moment** | Too many requests in a short window. The message says how long to wait. | **Try again** | | **The server failed** | DebugAI's side failed. The message is the server's own explanation when it sent one. | **Try again** | | **Analysis failed** | Anything else. The message carries the HTTP status or error code, which is what to quote in a bug report. | **Try again** | Full texts and fixes for each: [Answers and limits](/troubleshooting/answers). ## Insufficient context Sometimes the only fix is titled **Insufficient context for specific fix**, at 20%. DebugAI could not see enough code to name a cause, and the description says which of four things went wrong: ```text DebugAI saw the error text but had no project attached, so there was nothing to read your code from. Open your project folder in VS Code, run 'DebugAI: Index Entire Workspace', then try again. ``` No folder is open. Open your project folder, index it, and run the debug again. ```text DebugAI read the stack trace and found , but none of it is in your project index yet, so it could not see the code. Run 'DebugAI: Index Entire Workspace' and try again. Indexing runs once and covers every later error in this project. ``` The files are real but not indexed yet. [Index your project](/guides/index-your-project) and run it again. ```text The error names no file, so DebugAI had nothing to look up. Paste the full stack trace rather than the last line. If this error genuinely carries no frames, run 'DebugAI: Index Entire Workspace' so DebugAI can search your project for it instead. ``` You sent the last line of an error. Send the whole trace. When an editor file was sent along and it does not look like the source, the same advice reads: ```text The error names no file, and the open file does not appear to be where it came from. Paste the full stack trace rather than the last line — the frames are what let DebugAI find the source. ``` ```text DebugAI had your code and still could not narrow this to one fix. That usually means the cause is outside the files the trace names. Try the error again with more of the surrounding output, or open the file you suspect and run 'DebugAI: Analyze Error' there. ``` The index worked and the answer still was not specific. Send more of the output, or open the file you suspect and analyse from there. ## Next - [Apply and undo a fix](/guides/apply-and-undo). - [Verification](/concepts/verification), for what each label promises. # Work with your agent Source: https://docs.debugai.io/guides/work-with-your-agent Give your coding agent a loop that checks project memory before it guesses, debugs what is new, and records what worked. The DebugAI MCP server gives your agent three tools. Used in order, they stop it fixing the same bug from scratch every time: look up what this project already knows, debug what it does not, and report what happened. If it is not set up yet, start with [AI agents over MCP](/quickstart/agents). ### 1. Look it up first `lookup_error` checks whether this project has seen the error before. It makes no model call and does not count against your debug limit. It takes `errorText`, and optionally `filePath` (absolute) and `projectRoot`. A miss reads `Not seen before in this project (shop). Call debug_error with the full error for an analysis.` A hit says how many times the error was seen, and hands over what memory holds: - a **confirmed** fix: applied, and reported as working. The answer says whether a live session watched the error stop or the fix was only accepted; - an **unproven** fix: applied, and the error has come back once since; - an **anti-pattern**: the error came back two or more times after it, so it is named as the thing not to do; - advice that was tried here and reported as failed, under `Tried in this project recently and reported as FAILED. Do not repeat these:` The server allows 300 lookups per 15 minutes per account. ### 2. Debug what is new `debug_error` takes the error and returns a root cause and up to three ranked fixes. Each fix carries its confidence, its verification state, and where it can, exact `edits` (old and new strings an agent's edit tool can apply), a unified diff, and a check to run afterwards. It counts as one debug. | Input | What to pass | |---|---| | `errorText` | The full error or stack trace. Required. | | `reproCommand` | The command that shows the failure: a test, a script, a curl. Up to 500 characters. Fix 1 is aimed at making it pass, and each fix's check becomes this command. DebugAI never runs it. | | `expected` | What `reproCommand` should print or do once fixed. Up to 500 characters. | | `projectRoot` | The repository's absolute path, when the agent was started somewhere else. | | `filePath` | The file that threw. An absolute path also names its repository. | | `codeSnippet`, `snippetStartLine` | Code to analyse instead of reading files, and the file line it starts on. Usually unnecessary. | | `language` | Leave it on `auto` unless you have a reason. | The answer ends with a footer naming the project it was filed under, whether memory was on, and the server and engine versions, followed by a reminder to call `report_outcome` with its `debug_log_id`. DebugAI never writes to your files. Applying a fix is your agent's call, and yours. ### 3. Report what happened `report_outcome` takes the `debugLogId` and a `result`, and is what keeps memory honest: | Result | Means | |---|---| | `worked` | A fix was applied and the error stopped. It becomes this project's confirmed fix. Pass `fixRank` to say which. | | `worked_modified` | A fix held only after changes. `finalFix`, the code that actually held, is required and is what gets remembered. | | `failed` | A fix was applied and did not help. Later answers in this project are told not to repeat it. Pass `newError` with the error you saw next. | | `unused` | Nothing of DebugAI's was used. Also the answer for a repeat call about an error you already reported. | `actualFix` says what really fixed it when DebugAI's answer did not, up to 4,000 characters. `toolFeedback` says what would have made the tool more useful, up to 2,000. ## Make your agent do it every time The server tells agents what it is for when they connect, but a rule in the file your agent reads is the version that does not rely on the agent remembering. Add this to `CLAUDE.md`, `.cursorrules`, or your agent's equivalent: ```text When a command fails, call the debugai lookup_error tool first: it is instant and free. If it has no confirmed fix, call debug_error before attempting your own, and pass the command that reproduces the failure as reproCommand. After applying a fix, call report_outcome so the project's error memory stays accurate. ``` In Claude Code you can go further: a hook looks up every failed shell command in memory before the agent reacts to it, with no model call. See [Claude Code](/agents/claude-code). ## Which project, and what it reads The project is the git repository the server runs in, or the working folder when there is no repository. Memory and local reads are both scoped to it. `debug_error` reads the source files the stack trace names, so your agent does not have to paste them: - only inside the project, checked after symlinks are resolved; - only source files, by extension: `.ts .tsx .js .jsx .mjs .cjs .py .pyi .go .rs .rb .java .kt .kts .scala .groovy .gradle .php .cs .swift .dart .c .cc .cpp .h .hpp .ps1 .psm1 .psd1 .vue .svelte`; - at most 3 files, none over 2 MB, and 50,000 characters in all. A large file is sent as 40 lines on each side of the failing line; - never vendored folders such as `node_modules`, `site-packages`, `dist` and `.venv`. A `codeSnippet` replaces those reads. Every call that has a project also sends project facts: dependency names and versions from `package.json`, `requirements.txt`, `pyproject.toml` and `.csproj`, `.fsproj` or `.vbproj` files, which manifests exist, Python module names, virtual environment folder names, and whether `node_modules` and a `.env` exist. A `.env` file is never opened. The answer lists what it read, as `Read locally:` and the file names. Your home folder, the folders above it and the filesystem root are never a project, and under WSL neither is your Windows user folder (`/mnt/c/Users/you`). When the server finds nothing else, it reads nothing and says: ```text No local files read: there is no usable project root (none named, or only your home directory, a folder above it or the filesystem root, which are never one). Pass projectRoot to name the project. ``` Start your agent inside the repository, or tell it the folder ("the project is in /home/you/code/shop") so it passes `projectRoot`. It has to be an absolute path to a folder that exists. On Windows, the extension and the MCP server compute different project ids for the same checkout, so they keep two separate memories of it. ## In VS Code agent mode The extension registers the same tools for VS Code's agent mode, signed in with the extension's key. There, `filePath` does not name a project: pass `projectRoot` when the project is not the folder open in VS Code. See [VS Code agent mode](/agents/vscode-agent-mode). ## In ChatGPT and Codex The remote server behind the DebugAI plugin has the same three tools, plus `get_profile`. It cannot read your files or run code: it sees only what the conversation passes in, so paste the error and the code that matters. A call that names no project goes to a project called `chatgpt`. See [ChatGPT and Codex](/quickstart/chatgpt-codex). ## Next - [MCP tools reference](/reference/mcp-tools), every input and output field. - [Error memory](/concepts/error-memory), how a fix becomes "confirmed". - The server will not connect: [MCP troubleshooting](/troubleshooting/mcp). # Start here Source: https://docs.debugai.io/ Set up DebugAI where you write code, debug your first error, and learn to read what it tells you. DebugAI finds the root cause of an error by reading your project, not only the line you paste. It answers with up to three ranked fixes, and you review each one as a diff before anything in your files changes. ## Pick where you debug Install the extension, sign in with one browser click, debug the next error you hit. The same extension, installed from Open VSX. One command adds DebugAI to every MCP client on your machine. Connect the DebugAI plugin. Nothing to install. You can use more than one. They sign in to the same account and draw on the same daily limit. ## The first five minutes Every setup is the same four moves: 1. **Install** the extension, or run one command for your agent. 2. **Sign in.** Your browser opens, you confirm a short code, and you are connected. Free account, no card, no API key to copy. 3. **Index your project.** DebugAI reads your source files once, so an answer can point at the file that broke and not just the file that crashed. Skip this and it sees the error and the code around your cursor, not the rest of your project. See [Index your project](/guides/index-your-project). 4. **Debug an error.** From the terminal, the editor or your agent. You get a root cause and ranked fixes. No error to try it on? [Your first debug](/first-debug) gives you a three-file project with a bug planted in it, where the line that crashes is not the line that is wrong. ## What it costs 10 debugs a day on the free plan, with no card. The count resets at 00:00 UTC. A request DebugAI turns away because it is not an error, or one that fails on its side, is not counted. Pro is $12 a month for 1,000 debugs. See [Plans and limits](/reference/limits). ## When something goes wrong The troubleshooting pages are written by symptom. Their headings are the exact messages DebugAI shows, so you can search for the text on your screen with Ctrl K. - [Sign-in and keys](/troubleshooting/sign-in) - [Indexing](/troubleshooting/indexing) - [Answers and limits](/troubleshooting/answers) - [The MCP server](/troubleshooting/mcp) ## For your agent These docs are written for agents too. Add `.md` to any page address to get it as Markdown, or point your agent at [llms.txt](/llms.txt) for the index and [llms-full.txt](/llms-full.txt) for everything in one file. # AI agents quickstart Source: https://docs.debugai.io/quickstart/agents One command signs you in and adds DebugAI to Claude Code, Cursor, Windsurf and every other MCP client it finds. DebugAI runs as an MCP server, so your coding agent can call it the moment a command fails. The agent gets three tools: `lookup_error` checks your project's memory for free, `debug_error` finds the root cause and returns ranked fixes, and `report_outcome` records whether a fix worked. You need Node.js 18.14.1 or later. Check with `node -v`. The setup finds and configures these clients: Claude Code, Claude Desktop, Cursor, Windsurf, Zed, Gemini CLI and Cline. For VS Code's own agent mode, install the [extension](/quickstart/vscode) instead: it registers the server for you ([details](/agents/vscode-agent-mode)). ### 1. Run setup ```bash npx -y @debugai/mcp setup ``` It does three things, in order: 1. **Signs you in.** It prints a short code and opens your browser. Confirm the code on debugai.io (free account, no card). The key is saved to `~/.debugai/config.json` with file mode 0600, and every MCP client on this machine reads it from there. 2. **Adds DebugAI to every client it finds.** Each config file is backed up before the first change, and your other settings are kept. Your key is never written into a client's config. 3. **Checks the result** with `doctor`: your Node version, your key, whether the API answers, and which clients are wired up. To see what it would write before it writes anything: ```bash npx -y @debugai/mcp install --dry-run ``` The last line `doctor` prints is `✓ Everything checks out.` ### 2. Restart your client Each client picks up a new server differently. `setup` prints the step for every client it changed, and here they are in one place: | Client | What to do | |---|---| | Claude Code | Start a new session, or run `/mcp` to reconnect. | | Claude Desktop | Quit it completely and reopen it. Closing the window is not enough. | | Cursor | Nothing. It picks the server up on its own; Cursor Settings, MCP shows a green dot. | | Windsurf | Open Settings, MCP and press refresh. | | Zed | Nothing. Zed reloads settings on save, and the server appears in the agent panel. | | Gemini CLI | Restart the session. | | Cline | Open the Cline panel, then MCP Servers. It reconnects without restarting VS Code. | ### 3. Hand your agent an error Ask your agent to run something that fails and to use DebugAI on it, or paste an error and say "debug this with DebugAI". For example, with the project from [Your first debug](/first-debug): ```text Run python main.py. If it fails, use DebugAI to find the root cause before you change anything. ``` `debug_error` reads the files the stack trace names, from inside your project only, and answers with a root cause and up to three ranked fixes. Each fix says whether a mechanical check verified it. Your client shows a call to the `debug_error` tool from the `debugai` server, and the agent's answer names a root cause and a file and line in your project. ### 4. Tell your agent when to use it Agents follow their instructions file. Add this rule to `CLAUDE.md`, `.cursorrules` or your client's equivalent, so the agent checks memory first and reports back after a fix: ```text title="CLAUDE.md" When a command fails, call the debugai lookup_error tool first: it is instant and free. If it has no confirmed fix, call debug_error before attempting your own, and pass the command that reproduces the failure as reproCommand. After applying a fix, call report_outcome so the project's error memory stays accurate. ``` `lookup_error` makes no model call and does not count against your daily limit. Reporting outcomes is what lets the next occurrence of the same error arrive with the fix that held. More in [Work with your agent](/guides/work-with-your-agent). ## Skipped the sign-in? The server still starts. The first tool call hands your agent a sign-in link and a code to pass on to you. Confirm the code in your browser, and the agent can call the tool again. The client does not need restarting. ## Claude Code can look up every failed command A hook runs `lookup_error` on each failed shell command, so Claude Code hears what your project's memory knows about that error before it starts guessing. It makes no model call and costs nothing. Setup is in [Claude Code](/agents/claude-code). ## Undo it ```bash npx -y @debugai/mcp uninstall ``` This takes DebugAI back out of every client config it can find. The backups stay where `setup` put them. ## Next - One page per client, with the exact file each one uses: [Claude Code](/agents/claude-code), [Cursor](/agents/cursor), [Windsurf](/agents/windsurf), [Claude Desktop](/agents/claude-desktop), [Zed](/agents/zed), [Gemini CLI](/agents/gemini-cli), [Cline](/agents/cline), [other clients](/agents/other-clients). - [The MCP server](/troubleshooting/mcp), when `doctor` reports a problem. - [MCP tools](/reference/mcp-tools), every input and output. # ChatGPT and Codex Source: https://docs.debugai.io/quickstart/chatgpt-codex Connect the DebugAI plugin to ChatGPT or Codex and sign in with your DebugAI account. Nothing to install. The DebugAI plugin is a server DebugAI runs at `https://mcp.debugai.io/mcp`. ChatGPT and Codex connect to it over MCP and you sign in to DebugAI once, in your browser. It uses your normal DebugAI account, with the same plan and daily limit as the extension. If you have no account yet, that first sign-in creates a free one. It has four tools: `lookup_error`, `debug_error`, `report_outcome`, and `get_profile`, which tells ChatGPT which account is connected. Unlike the extension and the npm MCP server, the plugin cannot read your files. It sees only what the model puts in the tool call. Paste the full error, with the stack trace, and the code around it. The more of the real code it gets, the more specific the answer. ## ChatGPT If DebugAI is listed when you search [ChatGPT's plugins](https://chatgpt.com/plugins), install it from there and go to step 3. Otherwise add it yourself: ### 1. Add DebugAI as a custom MCP server Open [chatgpt.com/plugins](https://chatgpt.com/plugins), press the plus button and choose **Add custom MCP server**. Fill in: | Field | Value | |---|---| | Name | `DebugAI` | | MCP server URL | `https://mcp.debugai.io/mcp` | | Authentication | OAuth | Read the warning, choose **I understand and want to continue**, then **Create as a plugin**. ChatGPT lists the four tools it found. Workspace policies can turn custom servers off. On a Business or Enterprise workspace, ask your admin. ### 2. Install it and sign in Install the plugin. When ChatGPT sends you to DebugAI, sign in and approve. ChatGPT keeps a sign-in token for your DebugAI account until you disconnect the plugin. ### 3. Use it in a chat Start a new conversation, type `@` and pick DebugAI. Then paste the error and the code, and ask it to debug. When you have tried a fix, say so, for example "I tried fix 1 and it worked, record it". That calls `report_outcome`, and the next time the same error comes up, DebugAI leads with the fix that held. ChatGPT shows it used DebugAI, and the answer names a root cause and ranked fixes, each marked verified, failed check or not checked. ## Codex Codex keeps MCP servers in `~/.codex/config.toml`. OpenAI's documentation says the Codex CLI, the IDE extension and the ChatGPT desktop app share that file, so this setup covers all three. ### 1. Add the server ```bash codex mcp add debugai --url https://mcp.debugai.io/mcp ``` That writes this entry, which you can also add by hand: ```toml title="~/.codex/config.toml" [mcp_servers.debugai] url = "https://mcp.debugai.io/mcp" ``` ### 2. Sign in ```bash codex mcp login debugai ``` Your browser opens on DebugAI. Sign in and approve. ### 3. Check it is there Run `codex mcp list`, or type `/mcp` inside the `codex` session. DebugAI should be listed with its tools. ## Projects and memory Each tool call can name a project. A call that names none goes to a project called `chatgpt`, so ChatGPT and Codex share one memory unless you name your projects, for example "this is the checkout service". Memory here is separate from the memory the extension keeps for a folder on your machine. ## What DebugAI receives Only what each tool call carries: the error text and, when the model passes them, a code snippet, a file name, a language and a project name. Never your conversation. Before a file name is used, DebugAI removes your home folder from it and keeps the last three parts of the path. The details, including what is kept and for how long, are in the [privacy policy](https://debugai.io/privacy?src=docs#chatgpt-and-codex). To stop it, disconnect DebugAI in ChatGPT's or Codex's settings. Disconnecting does not delete what is already kept; email privacy@debugai.io from your account's address for that. The ChatGPT and Codex steps follow OpenAI's own guides as of that date. Their menus change. If a label here no longer matches, the two things that matter are the address `https://mcp.debugai.io/mcp` and OAuth sign-in. ## Next - [Work with your agent](/guides/work-with-your-agent): when to call each tool. - [MCP tools](/reference/mcp-tools): every input and output of the four tools. - Want DebugAI to read your files? Use the [npm server](/quickstart/agents) in a coding agent, or the [extension](/quickstart/vscode). # Cursor, Windsurf, VSCodium Source: https://docs.debugai.io/quickstart/cursor-windsurf-vscodium Install DebugAI from Open VSX in a VS Code fork, then sign in, index and debug exactly as in VS Code. Cursor, Windsurf and VSCodium install extensions from Open VSX, not the VS Code Marketplace. DebugAI is published on both, so everything after the install works the same as in VS Code. DebugAI needs an editor built on VS Code 1.101 or later. If it will not install, update the editor first. ### 1. Install from Open VSX In your editor, open the extensions panel, search for **DebugAI** and install it. Or open [DebugAI on Open VSX](https://open-vsx.org/extension/debugai/debugai). When it is installed, the status bar reads **DebugAI: Get Free Key** and a notice offers to sign you in. ### 2. Sign in Open the Command Palette (Ctrl Shift P, or Cmd Shift P on a Mac) and run **DebugAI: Sign In**. Your browser opens on debugai.io with a short code that is already on your clipboard. Sign in or create a free account, check the code, and press **Connect it**. The editor shows **DebugAI connected (free, 10/day)**. Signed in on the website already? The [dashboard](https://debugai.io/dashboard?src=docs) has a **Connect** button with a chip for Cursor, Windsurf and VSCodium. It opens your editor with the key filled in. ### 3. Index your project Press **Index workspace** on the **DebugAI connected** message, or run **DebugAI: Index Entire Workspace**. After this first time, DebugAI indexes on its own each time the editor starts. [Index your project](/guides/index-your-project) explains what is sent and what never is. ### 4. Debug an error Run the failing command in the editor's terminal, right-click inside the terminal and pick **DebugAI: Analyze Terminal Error**. For an error in a file, select it and press Ctrl Alt D (Cmd Alt D on a Mac). A **DebugAI** panel opens with a **Root Cause** that names a file and a line in your project, and ranked fixes under it. ### 5. Apply a fix Press **Preview & Apply Fix**, read the diff, then press **Apply**. **Undo** stays on the card for 30 seconds. The [VS Code quickstart](/quickstart/vscode) shows every step of this in detail, and it is the same here. ## Your editor's agent can use DebugAI too The extension gives you editor commands. Cursor's and Windsurf's own agents reach DebugAI through its MCP server, which is a separate, one-command setup: - [Cursor](/agents/cursor) - [Windsurf](/agents/windsurf) You can have both. They use the same account. ## Next - [Your first debug](/first-debug), on a planted bug. - [Read a result](/guides/read-a-result). - [Sign-in and keys](/troubleshooting/sign-in), if the browser step does not connect. # VS Code quickstart Source: https://docs.debugai.io/quickstart/vscode Install the extension, sign in, index your project and debug your first error. You need VS Code 1.101 or later and a project folder. DebugAI reads Python, JavaScript and TypeScript best. Java and C# files are indexed and analysed too. Using Cursor, Windsurf or VSCodium? Install from Open VSX instead ([see how](/quickstart/cursor-windsurf-vscodium)), then come back to step 2. Everything after the install is the same. ### 1. Install the extension Open [DebugAI on the Marketplace](https://marketplace.visualstudio.com/items?itemName=debugai.debugai) and press **Install**. Or in VS Code, open the Extensions view (Ctrl Shift X, or Cmd Shift X on a Mac), search for **DebugAI** and install it. From a terminal: ```bash code --install-extension debugai.debugai ``` Once it is installed, the status bar at the bottom right reads **DebugAI: Get Free Key** and a notice offers to sign you in. ### 2. Sign in Open the Command Palette (Ctrl Shift P, or Cmd Shift P) and run **DebugAI: Sign In**. Or press **Sign in** on the notice. Your browser opens on debugai.io with an eight-character code, and the same code is already on your clipboard. Sign in, or create a free account (no card), then check the code matches the one VS Code shows and press **Connect it**. You can close the tab. Back in VS Code you will see **DebugAI connected (free, 10/day)**. The code expires after 10 minutes. On a machine with no browser, such as a remote server over SSH, the notice gives you the address instead: open it on any device and type the code. ### 3. Index your project On the **DebugAI connected** message, press **Index workspace**. If the message is gone, run **DebugAI: Index Entire Workspace** from the Command Palette. The status bar shows **DebugAI indexing...** with a percentage. When it finishes you get a count, for example **Indexed 42 files. DebugAI can now trace an error across your codebase.**, and a panel listing the files it stored. You only do this by hand once. From the next time VS Code starts, DebugAI indexes the project on its own, and sends each file again when you open or save it. The text of your source and config files, up to 50 KB each and up to 500 files per run. The free plan keeps 200 files per project. `.env` files, key files and folders like `node_modules` are never sent. To stop automatic indexing, turn off the `debugai.autoIndex` setting. More in [Index your project](/guides/index-your-project). ### 4. Debug an error Run the command that fails in VS Code's own terminal. Then right-click inside the terminal and pick **DebugAI: Analyze Terminal Error**. DebugAI shows the error it found, starting with **Found in terminal:**, and you press **Analyze This**. If the error is in a file instead, select the error text and press Ctrl Alt D (Cmd Alt D on a Mac). That runs **DebugAI: Analyze Error**. With nothing selected, it offers the line under your cursor if that line reads as an error, and otherwise asks you to paste one. The answer opens in a **DebugAI** panel beside your code. The panel shows a **Root Cause** that names a file and a line in your project, with one or more **Ranked Fixes** under it. The status bar now counts what is left today, for example **DebugAI (9 left)**. ### 5. Review the fix and apply it Each fix has a confidence figure and one of three labels: **✓ Verified** (a mechanical check passed), **✗ Failed check** (DebugAI disproved it and capped its confidence) or **Not verified** (the figure is the model's own estimate). [Read a result](/guides/read-a-result) explains every part of the panel. Press **Preview & Apply Fix**. VS Code opens a diff titled **DebugAI: Review Fix #1** with the file name. Read it like a pull request, then press **Apply** on the fix card, or **Cancel**. After applying, the card offers **Undo** for 30 seconds. Ctrl Z in the file works too, because the change goes through the editor like your own typing. Run the failing command again to confirm the fix. ## No error to try it on - Run [Your first debug](/first-debug): a three-file project with a planted bug, where the crash and the cause are in different files. It uses one of your 10 free debugs. - Or run **DebugAI: Try Demo Analysis**. It opens a pre-made answer to a Celery worker crash, so you can see the panel without a project. It makes no request and does not count, and its fixes cannot be applied. ## Next - [Read a result](/guides/read-a-result): confidence, the three labels, and the memory badges. - [Proactive Scan](/guides/proactive-scan): DebugAI reads your recent changes and reports defects it can prove. - [VS Code agent mode](/agents/vscode-agent-mode): the extension already registers DebugAI as an MCP server for VS Code's agent mode. - Something not working: [Sign-in and keys](/troubleshooting/sign-in), [Indexing](/troubleshooting/indexing). # Commands and shortcuts Source: https://docs.debugai.io/reference/commands Every command the VS Code extension adds, where each one appears, and the one default keyboard shortcut. The extension adds 13 commands. Open the Command Palette (Ctrl Shift P, or Cmd Shift P on a Mac) and type **DebugAI** to list them all. The same commands run in Cursor, Windsurf and VSCodium. ## All commands | Command | ID | What it does | | --- | --- | --- | | DebugAI: Analyze Error | `debugai.analyze` | Debugs the error you selected, the error on the line under your cursor, or one you paste. | | DebugAI: Analyze Terminal Error | `debugai.analyzeTerminal` | Finds the last failing command in the terminal and debugs its error. | | DebugAI: Sign In | `debugai.signIn` | Connects the editor to your account with a code you confirm in the browser. | | DebugAI: Set API Key | `debugai.setApiKey` | Offers the browser sign-in, or a box to paste a key that starts with `dbg_`. | | DebugAI: Clear API Key | `debugai.clearApiKey` | Removes the stored key from this editor and signs it out. | | DebugAI: Index Entire Workspace | `debugai.indexWorkspace` | Indexes the open project now, whatever `debugai.autoIndex` says. | | DebugAI: Index Current File | `debugai.indexProject` | Indexes only the file in the active editor. The ID says project; the command does one file. | | DebugAI: Check Index Status | `debugai.checkIndex` | Says whether indexing is running, or how many files this window has indexed. | | DebugAI: Scan Workspace (Proactive) | `debugai.scanWorkspace` | Runs a [Proactive Scan](/guides/proactive-scan) of the files you changed recently. | | DebugAI: Debug in Browser | `debugai.debugInBrowser` | Opens your local dev server in Chrome or Edge and catches errors the terminal never shows. Closed beta, see [Debug in Browser](/guides/debug-in-browser). | | DebugAI: Show Browser Captures | `debugai.browserCaptures` | Lists the errors caught in the current browser session, to pick one to debug. | | DebugAI: Try Demo Analysis | `debugai.runDemo` | Opens a pre-made answer to a sample crash. Needs no key, makes no request and does not count. | | DebugAI: Open Dashboard | `debugai.openDashboard` | Opens your dashboard on debugai.io in the browser. | ## Where else they appear | Place | What runs | | --- | --- | | Right-click in the editor | **DebugAI: Analyze Error**, while the editor has focus | | Right-click in the terminal | **DebugAI: Analyze Terminal Error** | | The DebugAI item in the status bar, signed in | **DebugAI: Analyze Error** | | The same item, signed out (it reads **DebugAI: Get Free Key**) | **DebugAI: Open Dashboard** | | **Analyze error from terminal**, a button in the results panel | **DebugAI: Analyze Terminal Error** | | **Fix with DebugAI**, the quick fix on a DebugAI warning in the Problems panel | **DebugAI: Analyze Error** | | **DebugAI: watching**, the status bar item during a browser session | **DebugAI: Show Browser Captures** | The status bar item also counts what is left on your plan, for example **DebugAI (9 left)** on a daily plan or **DebugAI (120/1000)** on a monthly one. ## Keyboard shortcut There is one default shortcut. | Keys | Command | When | | --- | --- | --- | | Ctrl Alt D (Windows, Linux) | `debugai.analyze` | The editor has focus | | Cmd Alt D (macOS) | `debugai.analyze` | The editor has focus | It does nothing while the terminal has focus. From the terminal, right-click and pick **DebugAI: Analyze Terminal Error**, or give that command a shortcut of its own. ## Add your own shortcut Run **Preferences: Open Keyboard Shortcuts (JSON)** from the Command Palette and add an entry. The key below is an example; pick any combination your editor does not already use. ```json title="keybindings.json" [ { "key": "ctrl+alt+shift+d", "command": "debugai.analyzeTerminal" } ] ``` Add `"when": "terminalFocus"` to the entry if you want the shortcut to work only while the terminal has focus. Any command ID from the table above can be bound the same way. The extension also registers `debugai.openAnnouncement`, which has no title. It is what a click on a pinned product notice in the status bar runs. You do not need to call it. ## Related - [Settings](/reference/settings): the four `debugai.*` settings. - [Debug an error](/guides/debug-an-error): which command to use for which kind of error. # Plans and limits Source: https://docs.debugai.io/reference/limits What each plan includes, what counts as a debug, when counters reset, and every size, rate and time limit DebugAI applies. Prices change on the pricing page first. If this page and [debugai.io/pricing](https://debugai.io/pricing?src=docs) ever disagree, the pricing page is right. ## Plans | | Free | Pro | Team | | --- | --- | --- | --- | | Price | $0 | $12 a month, or $120 a year | $18 per seat a month, or $180 per seat a year. Minimum 3 seats | | Debugs | 10 a day | 1,000 a month included | 5,000 a month, pooled across seats | | At the limit | New debugs stop until the reset | You are told, and not stopped | You are told, and not stopped | | Proactive Scans | 3 a day, 3 files each | 22 a day, 10 files each | 52 a day, 10 files each | | Models | Haiku | Haiku, and Sonnet on hard errors | Haiku, and Sonnet on hard errors | The extension, the MCP server and the ChatGPT and Codex plugin all draw on the same account and the same counter. - **Pro trial.** 14 days of Pro with no card. It never starts on its own: start it on the [upgrade page](https://debugai.io/upgrade?src=docs) with **Try Pro free for 14 days**. When it ends without a subscription, the account is on Free again. - **Team.** Self-serve Team checkout is not live yet. Email [support@debugai.io](mailto:support@debugai.io) and the account is set up by hand. - **Founding rate.** Accounts created before the founding cutoff can claim Pro at $9 a month for life. The dates are on the [pricing page](https://debugai.io/pricing?src=docs). ## What counts as a debug One debug is one error you send and get an answer for, from any surface. These do not count: - A request DebugAI turns away because it is not an error, such as a terminal prompt or a block of source code. The answer says `This attempt was not counted against your limit.` - A request that fails on DebugAI's side. Its slot is handed back. - `lookup_error` and the Claude Code hook. Both read memory with no model call. - **DebugAI: Try Demo Analysis**, which makes no request at all. - Proactive Scans, which have their own daily count. ## When counters reset | Counter | Resets | | --- | --- | | Free daily debugs | Every day at 00:00 UTC | | Pro and Team monthly debugs | On the 1st of each month at 00:00 UTC | | Proactive Scans | Every day at 00:00 UTC | ## At the limit On Free, the 11th debug of the day is refused until 00:00 UTC. The extension says `Daily limit reached (10 a day). It resets at midnight UTC.` An agent gets the `quota_exceeded` error, which tells it not to retry. When two or fewer debugs are left, the extension warns you after a debug. On Pro and Team, 1,000 and 5,000 are soft caps. Past them you keep getting answers, and the extension tells you once a month, with a line on the dashboard. A separate ceiling, well above anything a person types, stops runaway scripts. If an account ever reaches it, debugs are refused until the 1st with `Monthly usage ceiling reached. Contact support if this is legitimate.` Write to [support@debugai.io](mailto:support@debugai.io) if that happens to you. ## Proactive Scans | Plan | Scans a day | Files per scan | | --- | --- | --- | | Free | 3 | 3 | | Beta (invited accounts) | 5 | 10 | | Pro | 22 | 10 | | Team | 52 | 10 | A project's first scan may read up to 18 files, and stops after 3 findings. Over the daily count the extension shows `DebugAI: Daily scan limit reached` with an **Upgrade** button. A scan request times out after 120 seconds. More in [Proactive Scan](/guides/proactive-scan). ## Sizes | What | Limit | | --- | --- | | Error text | 3,000 characters. The extension and the MCP servers cut longer text to fit, keeping its start and end. | | Code sent with a debug | 50,000 characters. The extension sends up to 30 lines either side of your cursor, fitted to that. | | Files the npm MCP server reads for one debug | 3 files, none over 2 MB, 50,000 characters in all | | Code snippet through the ChatGPT and Codex plugin | Its first 20,000 characters | | Report notes (`newError`, `actualFix`, `finalFix`) | 4,000 characters each from the npm server, 20,000 through the plugin | | One file in the index | 50 KB. A longer file is cut there. | | One indexing run | Up to 500 files sent, chosen from up to 4,000 that match | | Files kept per project on Free | 200. Pro and Team have no file cap. | ## Rate limits These stop floods, not people. | What | Limit | Counted per | | --- | --- | --- | | Any request to the API | 2,000 per 15 minutes | Network address | | Indexing requests | 600 per 15 minutes | Account | | Memory lookups (`lookup_error`, the hook) | 300 per 15 minutes | Account | | Starting a sign-in code | 30 per 15 minutes | Network address | | Checking whether a sign-in code was confirmed | 90 a minute | Network address | A burst over a limit gets a wait time back: `Too many requests in a short window. Wait about N seconds.` in the extension, and `rate_limited` with the seconds for an agent. No plan raises these limits. A sign-in code lives 10 minutes, and the extension and the CLI check it every 5 seconds. ## Timeouts | Where | Waits up to | | --- | --- | | The extension, for one debug | 110 seconds | | The API, for the engine's answer | 90 seconds | | The npm MCP server, `debug_error` | 150 seconds, or `DEBUGAI_TIMEOUT_MS` | | The npm MCP server, `lookup_error` and `report_outcome` | 8 and 15 seconds | | The ChatGPT and Codex plugin, for the engine | 50 seconds | | The extension, for a Proactive Scan | 120 seconds | | The Claude Code hook | 5 seconds for its input, 8 for the lookup | If your agent's client has its own tool timeout, set it above the `debug_error` wait. ## Which plan you are on The dashboard's **Settings** tab shows your plan, its limit and when the counter resets. The status bar shows what is left: **DebugAI (9 left)** on a daily plan, **DebugAI (120/1000)** on a monthly one. `npx -y @debugai/mcp status` prints the plan for the key your agent uses. A paused Pro or Team subscription counts as Free until it resumes. ## Related - [Answers and limits](/troubleshooting/answers): every limit message and what to do about it. - [Index your project](/guides/index-your-project) - [MCP tools](/reference/mcp-tools) # MCP CLI Source: https://docs.debugai.io/reference/mcp-cli Every command and flag of npx -y @debugai/mcp, what each one prints, the config files it writes, and the environment variables it reads. `@debugai/mcp` is the DebugAI MCP server and the command that sets it up. It needs Node.js 18.14.1 or newer. Run any command through `npx`: ```bash npx -y @debugai/mcp ``` Or install it once and call it as `debugai-mcp`: ```bash npm i -g @debugai/mcp@latest debugai-mcp ``` A global install does not update itself. Run the install command again when a new version ships. `npx -y @debugai/mcp --help` prints the same list as this page. ## Commands | Command | What it does | | --- | --- | | `setup` | Signs you in, adds DebugAI to every MCP client it finds, then runs `doctor`. | | `login` | Signs you in through the browser and stores the key. | | `logout` | Removes the stored key. | | `status` | Shows which API, which key and which account are in use. | | `install` | Adds DebugAI to MCP client configs, or removes it with `--remove`. | | `uninstall` | Removes DebugAI from every client config. | | `doctor` | Checks your Node version, your key, the API and each client's config. | | `hook` | The Claude Code hook that looks each failed shell command up in project memory. | | (none) | Runs the MCP server on stdio. This is what your MCP client starts. | ## setup ```bash npx -y @debugai/mcp setup ``` Runs `login`, then `install`, then `doctor`. If a key is already stored, login is skipped and it prints `✓ Already signed in — skipping login (use --force to re-link).` Flags after `setup` go to `install`. `--force` signs you in again even with a key stored. ```bash npx -y @debugai/mcp setup --client=cursor ``` ## login ```bash npx -y @debugai/mcp login ``` Starts a browser sign-in. It prints `Sign in to DebugAI`, a code in a box, and `Confirm that code at` followed by the address, opens your browser on that address, then waits: `Waiting… the code expires in 10 minutes. Ctrl-C to cancel.` On macOS it opens the browser with `open`, on Windows and WSL with `rundll32 url.dll,FileProtocolHandler`, and on Linux with `xdg-open`. It opens nothing when the `CI` variable is set or on Linux with no display. Then it prints the address for you to open on any device. Once you confirm the code in the browser: ```text ✓ Signed in as you@example.com (free tier). Key saved to /home/you/.debugai/config.json. Every MCP client on this machine reads it. Next: npx -y @debugai/mcp install (wires up the MCP clients you have) ``` | Flag | Effect | | --- | --- | | `--key dbg_…` | Stores a key you paste instead of signing in through the browser. For CI and machines with no browser. | | `--force` | Signs in again even when a working key is stored. Use it after rotating your key. | With a working key already stored, `login` says `✓ Already signed in as` your email and stops. When it fails: | Message | Meaning | | --- | --- | | `✗ Sign-in was declined in the browser.` | Someone pressed **Not me** on the confirm page. Nothing was stored. | | `✗ The code expired. Run "debugai-mcp login" again.` | Ten minutes passed before the code was confirmed. | | `✗ That does not look like a DebugAI key. They start with dbg_.` | The value passed to `--key` does not start with `dbg_`. | | `✗ Could not start the sign-in link: …` | The API could not be reached. It suggests `debugai-mcp login --key dbg_your_key` instead. | ## logout ```bash npx -y @debugai/mcp logout ``` Deletes the key from the config file and prints `✓ Stored key removed from` the file's path. If `DEBUGAI_API_KEY` is still set in your environment, it warns that the variable takes priority over the file. ## status ```bash npx -y @debugai/mcp status ``` Prints the API base, the key in masked form and where it came from (the config file or `DEBUGAI_API_KEY`), and the account and plan it belongs to. It exits with code 1 when there is no key, or when the key is rejected or the API cannot be reached. ## install ```bash npx -y @debugai/mcp install ``` Adds DebugAI to every MCP client it detects on this machine. A client counts as detected when its config file or its app folder exists. | Flag | Effect | | --- | --- | | `--list` | Shows every supported client, whether it was found, and where its config lives. Writes nothing. | | `--client=cursor` | Targets one client by ID. Comma-separate several: `--client=cursor,zed`. | | `--all` | Every supported client, detected or not. VS Code is still left out. | | `--dry-run` | Prints what each file would look like, and writes nothing. | | `--remove` | Takes the DebugAI entry back out. | For each client it prints one of: - `✓ Cursor — added to` the file, or `updated in` the file, followed by `backup:` and `next:` lines. The backup sits next to the original as `.debugai-backup-`, and `next:` says how to make that client pick DebugAI up. - `✓ Cursor — already configured, nothing to change` - `✗ Cursor — could not parse (…) — left untouched`, followed by `merge this in by hand:` and the entry to paste. It ends with `✓ Key already stored — restart the clients above and you are done.`, or with `No API key stored yet — run npx -y @debugai/mcp login to finish.` when you have not signed in. `--dry-run` ends with `Dry run — nothing was written.` When no client is found it prints `No MCP clients detected on this machine.` and the full list. Before it changes a file, it copies it. It keeps every other setting in the file, keeps the file's permissions (and the link, if the file is a symlink), and replaces the file in one atomic step. JSON cannot hold comments, so a config file with comments loses them. `install` says when that happened, and the backup still has them; `--dry-run` tells you beforehand. The VS Code extension already registers the DebugAI MCP server in VS Code 1.101 and later, so `install` and `install --all` skip VS Code. Name it to add it anyway, for example on a machine without the extension: `npx -y @debugai/mcp install --client=vscode`. Do not use both, or your agent sees every DebugAI tool twice. See [VS Code agent mode](/agents/vscode-agent-mode). ## uninstall ```bash npx -y @debugai/mcp uninstall ``` The same as `install --remove --all`. It removes the DebugAI entry from every supported client, including the VS Code one and any Claude Code entries scoped to a single directory. Each file is backed up first. Your stored key stays; run `logout` to remove it too. ## doctor ```bash npx -y @debugai/mcp doctor ``` It prints its checks under four headings: `Runtime`, `Account`, `API` and `MCP clients`. These count as problems: - Node is older than 18.14.1. - No key is stored, or the key does not start with `dbg_`. - The key does not authenticate against the API, or the API cannot be reached. These are warnings, which it prints with the fix but does not count: - Outside Windows, the config file can be read by other users. The fix is `chmod 600` on the file. - A detected client has no DebugAI entry. The fix is `debugai-mcp install --client=` and the client's ID. - An entry runs `@debugai/mcp` with no version, so npx can run an old copy. - A Claude Code entry works in one directory only. - A client config holds an API key in plain text, which keeps failing after you rotate your key. It ends with `✓ Everything checks out.`, or with the count, such as `✗ 1 problem to fix.`, and then exits with code 1. Each problem line has a hint under it, usually the command that fixes it. ## hook ```bash npx -y @debugai/mcp@latest hook ``` You do not run this yourself. Claude Code runs it after a shell command fails, once you add it as a `PostToolUseFailure` hook. Setup: [Claude Code](/agents/claude-code). - It acts only on `Bash` and `PowerShell` tool failures with a non-zero exit code that were not interrupted, and only when the output has at least 12 characters. - It looks the output up in this project's memory: the same lookup as `lookup_error`, with no model call, and it does not count against your plan. - It prints only when memory has something: a stored fix, or a fix this project reported as failed. Its answer goes to the agent beside the failure, cut to 9,000 characters. - It reads the key `login` stored, or `DEBUGAI_API_KEY`, and never starts a sign-in. - It waits at most 5 seconds for its input and 8 seconds for the lookup, and always exits with code 0, so it never blocks the agent. - It sends the failed command's output, up to 3,000 characters, and the project ID. The command line is not sent. ## Running the server ```bash npx -y @debugai/mcp ``` Runs the MCP server on stdio and waits for a client to speak first, so in a terminal it looks like nothing is happening. That is correct. It logs to stderr only, starting with a line like `[debugai-mcp] v2.7.0 connected on stdio`, or a note that no key is stored yet. Without a key, the first tool call hands your agent a sign-in link, and nothing needs restarting once you confirm it. ## Clients and the files `install` writes "AppData" below is `%APPDATA%` on Windows (by default `~/AppData/Roaming`), `~/Library/Application Support` on macOS, and `$XDG_CONFIG_HOME` or `~/.config` on Linux. | ID | Client | Config file | Key | | --- | --- | --- | --- | | `claude-code` | Claude Code | `~/.claude.json` | `mcpServers` | | `claude-desktop` | Claude Desktop | `AppData/Claude/claude_desktop_config.json` | `mcpServers` | | `cursor` | Cursor | `~/.cursor/mcp.json` | `mcpServers` | | `windsurf` | Windsurf | `~/.codeium/windsurf/mcp_config.json` | `mcpServers` | | `zed` | Zed | Windows: `AppData/Zed/settings.json`. macOS and Linux: `$XDG_CONFIG_HOME/zed/settings.json`, or `~/.config/zed/settings.json` | `context_servers` | | `gemini-cli` | Gemini CLI | `~/.gemini/settings.json` | `mcpServers` | | `cline` | Cline (VS Code) | `AppData/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` | `mcpServers` | | `vscode` | VS Code (native MCP), opt-in | `AppData/Code/User/mcp.json` | `servers` | The entry is the same everywhere except Zed and VS Code, and it never contains your key: ```json { "mcpServers": { "debugai": { "command": "npx", "args": ["-y", "@debugai/mcp@latest"] } } } ``` ```json { "context_servers": { "debugai": { "source": "custom", "command": { "path": "npx", "args": ["-y", "@debugai/mcp@latest"] } } } } ``` ```json { "servers": { "debugai": { "type": "stdio", "command": "npx", "args": ["-y", "@debugai/mcp@latest"] } } } ``` Keep the `@latest`. Without a version, npx runs the first copy it finds, and an old global install wins over the newest release. ## Where the key lives `login` writes the key to one file, and every MCP client on the machine reads it from there: ```json title="~/.debugai/config.json" { "api_key": "dbg_…" } ``` Outside Windows the file is created with mode `0600` and its folder with `0700`, so only your user can read it. The file can also hold `api_base`. Set `DEBUGAI_CONFIG_PATH` to keep it somewhere else. ## Environment variables Environment variables win over the config file. | Variable | Default | What it does | | --- | --- | --- | | `DEBUGAI_API_KEY` | none | A key to use instead of the stored one. | | `DEBUGAI_API_BASE` | DebugAI production, `https://debugai-mvp-production.up.railway.app/api` | Another API address, for staging or self-hosted setups. Falls back to `api_base` in the config file. | | `DEBUGAI_TIMEOUT_MS` | `150000` | How long `debug_error` waits for an answer, in milliseconds. `lookup_error` always waits 8 seconds and `report_outcome` 15; the hook ignores this variable. | | `DEBUGAI_CONFIG_PATH` | `~/.debugai/config.json` | Another location for the config file. | ## Related - [AI agents quickstart](/quickstart/agents) - [MCP tools](/reference/mcp-tools): what the server gives your agent. - [The MCP server](/troubleshooting/mcp): when it does not connect. # MCP tools Source: https://docs.debugai.io/reference/mcp-tools The tools each DebugAI MCP server gives your agent, every input they take, what they return, and the errors an agent can get back. There are three DebugAI MCP servers, and they share one account and one set of plan limits: | Server | Who starts it | Tools | | --- | --- | --- | | `@debugai/mcp` on npm | Your MCP client, from the entry `setup` writes | `lookup_error`, `debug_error`, `report_outcome` | | The one inside the VS Code extension | VS Code 1.101 and later, on its own | `lookup_error`, `debug_error`, `report_outcome` | | `https://mcp.debugai.io/mcp` | ChatGPT and Codex, over the network | `lookup_error`, `debug_error`, `report_outcome`, `get_profile` | Most of this page is the npm server. The other two are at the end, with what differs. The loop the tools are built for: call `lookup_error` first, since it is free. If it has no confirmed fix, call `debug_error`. After trying a fix, call `report_outcome`, so the next time that error comes back in the project, memory knows what worked. See [Work with your agent](/guides/work-with-your-agent). ## lookup_error **Look Up Error in Project Memory.** Checks whether this project has seen the error before. No model call, and it does not count against your plan. Declared hints: `readOnlyHint`, `idempotentHint`, and `openWorldHint: false`. | Input | Type | Required | What it is | | --- | --- | --- | --- | | `errorText` | string | yes | The error or stack trace, as you would pass it to `debug_error`. | | `filePath` | string | no | An absolute path inside the repository the error came from. | | `projectRoot` | string | no | The repository's absolute path, when the server started somewhere else. Memory is scoped to it. | It answers in plain text, such as `Not seen before in this project (shop). Call debug_error with the full error for an analysis.`, or how many times it was seen and the fix confirmed for it. Fixes reported as failed in this project come under `Tried in this project recently and reported as FAILED. Do not repeat these:`. The structured result has `memory_enabled`, `memory_disabled_reason`, `memory_hit`, `memory_times_seen`, `memory_fix_state` (`none`, `confirmed`, `unproven` or `anti_pattern`), `memory_recurrences_after_fix`, `memory_verified_count`, `last_seen_at`, `stored_fix`, `refuted` (each with `at`, `rank`, `title` and `what_happened`), `project` and `mcp_version`. The API allows 300 lookups per 15 minutes per account. ## debug_error **Debug Error.** Finds the root cause of an error and returns up to three ranked fixes. It uses one debug from your plan and saves the analysis to your history and the project's memory. It does not change your files. Declared hints: `readOnlyHint`. | Input | Type | Required | What it is | | --- | --- | --- | --- | | `errorText` | string | yes | The full error, exception or stack trace. | | `language` | string | no | A hint, `"auto"` by default. One of `javascript`, `typescript`, `python`, `go`, `rust`, `java`, `csharp`, `cpp`, `c`, `php`, `ruby`, `kotlin`, `swift`, `lua`, `shell`, `powershell`, `sql`, `html`, `css`, `scala`, `dart`, `elixir`, `r`, `perl`. Any other value is treated as `"auto"`, never refused. | | `codeSnippet` | string | no | Code to analyse instead of what the server reads off disk. Only needed when the code is somewhere the trace does not name. | | `snippetStartLine` | integer, 1 or more | no | With `codeSnippet`: the line of the file the snippet's first line is. | | `filePath` | string | no | The file that threw. An absolute path also tells DebugAI which repository the error belongs to. | | `reproCommand` | string, up to 500 characters | no | The command that reproduces the failure. DebugAI never runs it. Fix 1 is aimed at making it pass, and each fix's check becomes "run this". | | `expected` | string, up to 500 characters | no | What `reproCommand` should print or do once the bug is fixed. | | `projectRoot` | string | no | The repository's absolute path, when the server started somewhere else. Never your home folder, a folder above it, or the filesystem root. | Before it calls the API, the server reads the source files the stack trace names, from inside the project only: at most 3 files, none over 2 MB, 50,000 characters in all, and a window of 40 lines either side of the error in a large file. It also sends the project's declared dependencies. Error text over 3,000 characters is cut, keeping its start and end. [What leaves your machine](/concepts/privacy) has the full list. ### What it returns The text answer, in order: 1. `## Root Cause`, then the cause in plain words. 2. `## Fixes`, one block per fix, headed like `**Fix 1 (82% confidence)**` and the fix's title. 3. Under each fix, its verification line: `✓ Verified` or `✗ Failed mechanical check (confidence capped)` with the reason, or `· Not verified`, which says the confidence is the model's own estimate. Then the description, the code, `_File:_` when the fix edits another file, and `_Location:_`. 4. What project memory knows about the error, when it knows something. 5. A footer of badges: the files it read locally, the model, whether project code was used (`Codebase-aware: yes`), whether the answer was cached, the framework, the project and where its root came from, `Memory: off` when memory is off, a note when the error text was cut, the server version and the engine build. 6. A reminder to call `report_outcome` with this answer's `debugLogId`. The structured result: | Field | What it holds | | --- | --- | | `schema_version` | The response format version. | | `root_cause` | The cause, as text. | | `fixes` | Up to three fixes. Fields below. | | `debug_log_id` | The ID to pass to `report_outcome`. | | `framework_detected`, `model_used`, `engine_version` | What answered and what it recognised. | | `cached`, `has_project_context` | Whether the answer came from cache, and whether project code was used. | | `error_signature` | The error's normalised signature, which memory is keyed on. | | `memory_hit`, `memory_times_seen`, `memory_fix_confirmed`, `memory_fix_state`, `memory_enabled` | What project memory said about this error. | | `local_files_read` | The files the server read off disk. Empty when you passed `codeSnippet`. | | `project` | `root` and `source`, where the project came from: the argument you passed, or `cwd`. | | `error_text_cut`, `mcp_version` | How many characters were cut from the error, and the server version. | Each fix has `rank`, `title`, `description`, `confidence` (0 to 100), and when they apply `code`, `line_hint`, `file`, `verified` (`true`, `false` or `null`, where `null` means nothing checked it), `verification_reason`, `edits` (exact `file`, `old_string` and `new_string` replacements), `unified_diff`, `verify_with`, `verify_kind`, `verify_expect`, `syntax_check` and `previously_failed`. A fix only carries `edits` when the change can be stated as an exact replacement. [Verification](/concepts/verification) explains the three states. ## report_outcome **Report Fix Outcome.** Records what happened after a `debug_error` answer. A confirmed fix is remembered for the project and handed back the next time the same error comes up there. Call it once per answer. Declared hints: `idempotentHint`. | Input | Type | Required | What it is | | --- | --- | --- | --- | | `debugLogId` | string | yes | The `debug_log_id` from the answer you are reporting on. | | `result` | `worked`, `worked_modified`, `failed` or `unused` | yes | See below. | | `fixRank` | integer, 1 to 3 | no | Which fix you applied. Leave it out for `unused`. | | `newError` | string, up to 4,000 characters | no | With `failed`: the error that came after the fix. | | `actualFix` | string, up to 4,000 characters | no | What really solved it, when it was not DebugAI's fix. | | `finalFix` | string, up to 4,000 characters | with `worked_modified` | The code that finally worked, after your changes. It is what memory keeps. | | `toolFeedback` | string, up to 2,000 characters | no | What would have made DebugAI more useful on this call. It goes to the people who build it, not into project memory. | The four results: | Result | Use it when | | --- | --- | | `worked` | You applied a fix and the error stopped. | | `worked_modified` | A fix worked only after you changed it. Send the working code in `finalFix`. | | `failed` | You applied a fix and it did not help, or made things worse. | | `unused` | You applied none of them and solved it another way. Also the answer for a repeat call about an error you already reported. | Use `unused`, not `failed`, when nothing of DebugAI's was run. A `failed` report marks a fix as tried and beaten. It returns `{"recorded": true, "result": …}` and a sentence confirming what was saved. ## Errors your agent can get back Every failure comes back as a tool result with `isError` set, a sentence the agent can relay, and a structured `error_type`: | `error_type` | Cause | Retry? | | --- | --- | --- | | `not_linked` | No key yet. The answer carries a sign-in link and a code for the user to confirm. The client does not need a restart. | Yes, after the user confirms | | `auth_failed` | The key was rejected (HTTP 401 or 403). The fix is `npx -y @debugai/mcp login --force`. | No | | `quota_exceeded` | The daily debug limit is used up (HTTP 402). It says when it resets. | No | | `monthly_ceiling` | A paid account reached its monthly usage ceiling (HTTP 429). It resets on the 1st (UTC). | No | | `rate_limited` | Too many requests in a short window (HTTP 429). It says how many seconds to wait, 60 when the API gives no figure. | Yes, after the wait | | `invalid_request` | The API refused the arguments (HTTP 400) and says why. The same call is refused the same way. | No, change the arguments | | `not_found` | The `debug_log_id` is not one this account was given (HTTP 404), or `DEBUGAI_API_BASE` points somewhere wrong. | No | | `engine_unavailable` | The engine is down for a moment (HTTP 503 or 504). It points to `https://status.debugai.io`. | Yes, in 30 to 60 seconds | | `network_error` | The request never reached the API: offline, a proxy, or a wrong `DEBUGAI_API_BASE`. | Yes, once the network is back | | `unknown` | Anything else. | Yes | `quota_exceeded` and `monthly_ceiling` tell the agent plainly not to retry, because the same call is refused until the limit resets. [Plans and limits](/reference/limits) has the numbers. ## The server inside the VS Code extension VS Code 1.101 and later starts it on its own, under the name **DebugAI**, for agent mode. It has the same three tools with the same inputs. What differs: - It uses the key from the extension's sign-in. If the key is rejected, it tells the user to run **DebugAI: Set API Key** from the Command Palette. - Its project is the first folder open in VS Code. `projectRoot` is for an error from somewhere else. `filePath` does not name a project here. - Its waits are fixed: 150 seconds for `debug_error`, 15 for `report_outcome` and 8 for `lookup_error`. `DEBUGAI_TIMEOUT_MS` does not apply. - Its footer reads `DebugAI MCP` with the version and `(VS Code)`, and its status link is `https://debugai.io/status`. See [VS Code agent mode](/agents/vscode-agent-mode). ## The remote server, for ChatGPT and Codex `https://mcp.debugai.io/mcp` is a Streamable HTTP server. You sign in to your DebugAI account through OAuth, with Clerk as the sign-in service; ChatGPT or Codex offers the sign-in the first time a tool needs it. Setup: [ChatGPT and Codex](/quickstart/chatgpt-codex). It sees only what each call carries. It cannot read your files or run code, so the agent has to pass the error, and any code, in the call. | Tool | Title | Inputs | | --- | --- | --- | | `lookup_error` | Look up an error in DebugAI memory | `errorText`, `project` | | `debug_error` | Analyse an error | `errorText`, `codeSnippet`, `snippetStartLine`, `fileName`, `language`, `project` | | `report_outcome` | Record whether a fix worked | `debugLogId`, `result`, `fixRank`, `finalFix`, `newError`, `actualFix` | | `get_profile` | Show the connected DebugAI account | none | What differs from the npm server: - **Projects are names.** `project` is a short name such as `billing-api`, and memory is kept per name. A call that names none uses the project `chatgpt`, so ChatGPT and Codex share one memory unless you name projects. - **`fileName`** is a file name or a relative path, not a full path from your computer. - **Sizes.** `errorText` is cut to 3,000 characters, keeping its start and end, and `codeSnippet` to its first 20,000 characters. `finalFix`, `newError` and `actualFix` take up to 20,000 characters each. There is no `toolFeedback`. - **The engine gets 50 seconds** to answer on this path. - **Reports wait for a real try.** A `report_outcome` on an analysis less than 30 seconds old is refused, except `unused`, because nobody can have tried a fix that fast. - **`get_profile`** returns an `id` that means nothing outside DebugAI, and your display name. The structured results use camelCase. `debug_error` returns `outcome` (`analysed` or `not_an_error`), `debugLogId`, `rootCause`, `fixes`, `memory`, `debugsLeftToday` and `repeated`. Each fix has `rank`, `title`, `confidence`, `explanation`, `verification` (`passed`, `failed` or `not_checked`), `verificationNote`, `code`, `file`, `location`, `edits`, `checkCommand` and `previouslyFailed`. `lookup_error` returns `project`, `seenBefore`, `timesSeen`, `lastSeenDate`, `fixState`, `storedFix`, `confirmation` and `failedFixes`. `report_outcome` returns `recorded`, `alreadyRecorded` and `result`. Declared hints: `lookup_error` and `get_profile` are read-only and idempotent. `debug_error` is neither, since it spends a debug and saves the analysis. `report_outcome` is idempotent and marked destructive, because a fix reported as worked replaces the one memory had. ## Related - [MCP CLI](/reference/mcp-cli): installing the npm server and the Claude Code hook. - [Plans and limits](/reference/limits) - [Error memory](/concepts/error-memory) # Settings Source: https://docs.debugai.io/reference/settings The four settings the VS Code extension reads, their defaults, and what changes when you turn each one off. Open them with **Preferences: Open Settings (UI)** and search for **DebugAI**, or edit `settings.json` directly. They work the same in Cursor, Windsurf and VSCodium. | Setting | Type | Default | Scope | | --- | --- | --- | --- | | `debugai.apiKey` | string | `""` | application | | `debugai.autoIndex` | boolean | `true` | default (window) | | `debugai.showWelcome` | boolean | `true` | default (window) | | `debugai.showAnnouncements` | boolean | `true` | application | An **application** setting is one value for the whole editor, set in your user settings. The other two use VS Code's default scope, so a project can override them in its own `.vscode/settings.json`. ## debugai.apiKey Your DebugAI key, if you would rather paste one than sign in. You almost never need it: **DebugAI: Sign In** stores the key in VS Code's secret storage, which is encrypted and never written to `settings.json`. A key that starts with `dbg_` pasted into this setting is moved into secret storage the first time DebugAI uses it, and the setting is cleared. Until then it sits in `settings.json` as plain text, so do not paste a key here in a settings file you commit or sync. Your key is on the dashboard, under **Settings**. To replace or remove it, run **DebugAI: Set API Key** or **DebugAI: Clear API Key**. ## debugai.autoIndex With it on, DebugAI indexes the open project once when VS Code starts with you signed in, and again for each file you open or save. Each file sends its text to DebugAI's servers, up to 50 KB per file and up to 500 files per run. The free plan keeps 200 files per project. `.env` files and key files are never sent. Turn it off and nothing is indexed until you run **DebugAI: Index Entire Workspace** or **DebugAI: Index Current File** yourself. One exception: a [Proactive Scan](/guides/proactive-scan) indexes the files it picks before it reads them, whatever this setting says. The first time DebugAI indexes on its own, it says so in a notice with a **Turn off auto-index** button. That button sets this setting to `false` for your user settings. ## debugai.showWelcome After the first index of a new project, DebugAI opens a one-time panel that lists the files it stored and offers a [Proactive Scan](/guides/proactive-scan). Set this to `false` to skip the panel. Indexing still runs. ## debugai.showAnnouncements Shows DebugAI product notices in the editor: new features, beta access you were granted, and service notices. Set it to `false` to hide them. The dashboard keeps showing them either way. ## Example ```json title="settings.json" { "debugai.autoIndex": true, "debugai.showWelcome": false, "debugai.showAnnouncements": true } ``` To stop automatic indexing in one project only, put this in that project's `.vscode/settings.json`: ```json title=".vscode/settings.json" { "debugai.autoIndex": false } ``` ## Related - [Index your project](/guides/index-your-project): what indexing reads, what it never reads, and the caps. - [Commands and shortcuts](/reference/commands) - [What leaves your machine](/concepts/privacy) # Answers and limits Source: https://docs.debugai.io/troubleshooting/answers When a debug comes back thin, refused or not at all, and what each limit message means. Each heading below is the text DebugAI shows, without the `DebugAI:` in front. In the editor, a failed debug shows as a notification, and in the results panel when one is open. ## Insufficient context for specific fix When DebugAI cannot name a specific fix, it returns one fix with this title at 20% confidence. Its description says which of these happened. ### DebugAI saw the error text but had no project attached No folder was open, so there was no project to read code from. Open your project folder in VS Code, run **DebugAI: Index Entire Workspace**, then debug the error again. ### DebugAI read the stack trace and found …, but none of it is in your project index yet The stack trace named files in your project, and none of them was in the index. This is the usual reason on a project's first error. Run **DebugAI: Index Entire Workspace** and debug the error again. You only need to do this once per project. See [Indexing problems](/troubleshooting/indexing) if it does not finish. ### The error names no file, and the open file does not appear to be where it came from DebugAI had only the last line of the error. Paste the whole stack trace, not just the final message: the file and line frames are what lead DebugAI to your code. ### The error names no file, so DebugAI had nothing to look up The same, with no code to go on at all. Paste the full stack trace. If the error really carries no frames, run **DebugAI: Index Entire Workspace** so DebugAI can search your project for it instead. ### DebugAI had your code and still could not narrow this to one fix The index worked and DebugAI read your code, but the cause is probably outside the files the trace names. Debug the error again with more of the output around it, or open the file you suspect and run **DebugAI: Analyze Error** there. ## Paste the error itself When what you sent is not an error, DebugAI does not guess. The root cause becomes a one-line summary of what it received, and there is one fix, titled **Paste the error itself**, at 0% confidence, saying what to paste instead. That attempt is not counted against your limit. Sending the same text again gets the same answer, so change what you paste rather than retrying. ### That is a terminal prompt, not an error message. You sent the shell prompt, or commands you typed. Select the output that came after the command ran, starting at the first line with Traceback, Error or Exception. If the command printed nothing, there is no error to explain yet. ### That is a file path with no error message attached. You sent one line out of a stack trace. Select the whole block instead: the message line and every file line above it. ### There is not enough here to diagnose. Too short to be an error. Paste the whole block your program printed, with the file names and line numbers. ### No error text was supplied. Nothing was sent. Copy the error your program printed, from the word Traceback, Error or Exception to the end of the message. ### That is source code, not an error. You sent code rather than what went wrong with it. Run it, then send the error it prints. DebugAI reads the files your stack trace names by itself. ### No error message was found in that text. DebugAI found nothing that reads as an error. If your program is misbehaving without printing an error, describe it in this shape and DebugAI will take it: what you expected, what happened instead, and the code in between. For example, `getUser returns null for a valid id, expected the profile object`, followed by the function. When an AI agent calls `debug_error`, this one case is not refused: an agent's own description of a failure is analysed. Everything else on this list is refused for agents too. ### That looks like a DebugAI answer, not an error. You sent a DebugAI result back in. If the fix did not work, run the code again and send the new error. DebugAI then knows the previous fix did not hold. ### That is a DebugAI notification, not an error from your code. You sent one of DebugAI's own messages. If it was the indexing notice, the files it did index are already usable. Send the error your own program printed. ### That is a DebugAI setup command, not an error from your code. You sent a DebugAI setup command or its output. Run setup commands in a terminal, as in the [AI agents quickstart](/quickstart/agents). If setup itself fails, send that failure: an install error is analysed like any other. ## When a debug fails The panel and the notification say the same thing. Each has one button for the next step. ### The engine did not answer within 110 seconds. It may be busy. The extension waits 110 seconds for an answer. Press **Retry**. In the panel this is **The engine timed out**. ### Cannot reach DebugAI. Check your connection or firewall. The request never reached DebugAI. Check your connection, and that the hosts under [Behind a proxy or firewall](/troubleshooting/sign-in#behind-a-proxy-or-firewall) are reachable. Then press **Retry**. ### Your API key is invalid or expired. See [Sign-in and keys](/troubleshooting/sign-in#key-invalid). ### Daily limit reached (10 a day). It resets at midnight UTC. The free plan's 10 debugs for today are used. The count resets at 00:00 UTC. Refused pastes and failures on DebugAI's side never count, and neither does `lookup_error` or the Claude Code hook for agents. To keep going today, **See Pro pricing →** opens the plans. Pro is $12 a month with 1,000 debugs a month included, and you can try it free for 14 days from the [upgrade page](https://debugai.io/upgrade?src=docs), with no card. See [Plans and limits](/reference/limits). ### Monthly usage ceiling reached. Contact support if this is legitimate. Paid plans only. Pro's 1,000 debugs and Team's 5,000 are soft caps: past them you keep getting answers. Far above them sits a separate limit that exists to stop runaway scripts, and this account reached it. It resets on the 1st of the month (UTC). If your use is real, press **Open dashboard** and write to us from **Messages**. ### Too many requests in a short window. Wait about N seconds. A short burst limit. Wait the time it names, then press **Retry**. When there is no wait time to quote, the message says `Wait a little and try again.` instead. No plan raises this limit. In the panel this is **Slow down for a moment**. ### The server failed on this request (HTTP N). Something failed on DebugAI's side. When the AI model is what failed, the message says so in its own words instead, and that attempt is not counted against your limit. Press **Retry**. If it keeps failing, check [status.debugai.io](https://status.debugai.io) and write to support@debugai.io. ### The request was refused (HTTP N) DebugAI refused the request and says why after the colon. Sending the same request again fails the same way, so change what the reason names. If the reason does not make sense, send it to support@debugai.io. ### The request failed The request got no usable reply, and the code in brackets is the only detail there is. Press **Retry**. If it keeps happening, send that code to support@debugai.io. ## When a fix cannot be applied ### This error is inside a library file The stack trace points only at code you did not write, such as a package under `node_modules` or `site-packages`, so there is no file of yours to change and the apply button is off. Copy the fix into your own code, or press **Re-analyze error now →** to run **DebugAI: Analyze Terminal Error** again. The panel also suggests pasting the exact error into **DebugAI: Analyze Error** with your own file open, so DebugAI can find the file to change. Every other reason DebugAI declines to write a fix, and what to do about each, is in [Apply and undo a fix](/guides/apply-and-undo). ## Notices after a debug ### N debugs left today. Resets midnight UTC. Shown on the free plan when two or fewer debugs are left today. Nothing is wrong. ### You have used N debugs this month (L included on your plan). Shown once a month on Pro and Team, when you pass the debugs your plan includes. The message goes on to say that it is a heads-up, not a throttle, and that fair use applies above the included amount. Debugging keeps working. ## Proactive Scan messages Scans have their own daily limit, separate from debugs. More in [Proactive Scan](/guides/proactive-scan). ### Daily scan limit reached Today's scans are used. Free includes 3 a day, Pro 22 and Team 52. The count resets at midnight UTC. **Upgrade** opens the plans. ### Scanning is a paid feature Your account's plan includes no scans. The free plan includes 3 a day, so if you are on Free and see this, write to support@debugai.io. ### Scan failed (N). Try again. The scan request failed. Run **DebugAI: Scan Workspace (Proactive)** again. ## An answer looks wrong 1. Check the project is indexed, with **DebugAI: Check Index Status**. Most thin answers come from an index that is missing or partial. 2. Send the whole error, stack trace included, not only its last line. 3. Tell us. The thumbs down under an answer asks what went wrong: **Wrong fix**, **Wrong file**, **Off-target error**, **Too generic** or **Other**, and records your pick with that answer. **Other** opens the **Feedback** tab on your dashboard, where you can say more. # Indexing problems Source: https://docs.debugai.io/troubleshooting/indexing What each indexing message means, why a file was left out, and how to finish an index that stopped early. Indexing is what lets an answer point at the file that broke, not only the file that crashed. When an answer says DebugAI could not see your code, start here. Two commands tell you where you stand: - **DebugAI: Check Index Status** says what this window has indexed. - **View Details**, on the message an index run ends with, opens the **DebugAI Indexing** output with the list of files DebugAI stored. Each heading below is the message as DebugAI shows it, without the `DebugAI:` in front. `N` and `M` stand for the numbers on your screen. ## When an index run ends ### Indexed N files. DebugAI can now trace an error across your codebase. Nothing is wrong. Every file DebugAI tried was stored. **View Details** lists them. ### DebugAI indexed N files so far. The remaining M are queued for the next run in about 15 minutes. The run went faster than the server's limit allows (600 index requests per 15 minutes for an account), so it stopped early. The files it stored already work: you can debug now, and answers improve once the rest are in. Press **Finish indexing** after about 15 minutes, or run **DebugAI: Index Entire Workspace** again then. ### DebugAI indexed N files. M more in this project were not indexed, so answers that need them will be incomplete. The message goes on to say that nothing failed and there is nothing to retry, and that is true. One of two limits was reached: - **The free plan keeps 200 files per project.** Pro and Team have no per-project cap. - **One run sends at most 500 files, on any plan.** When a project has more, DebugAI picks which. Source files come before config files, though a tenth of the places is kept for config. Tests, snapshots and vendored files rank below other source. Running it again picks the same files. With `debugai.autoIndex` on, each file you open or save is sent on its own, so on Pro and Team the files you work in join the index as you go. ### Indexed N files. M could not be indexed and were not checked. Run indexing again to retry them. Some files failed for a reason that is neither a plan limit nor the rate limit, such as a dropped connection or a server error partway through. Press **Finish indexing**, or run **DebugAI: Index Entire Workspace** again. ### The server asked us to slow down before anything was stored. Nothing was indexed. Try again in about 15 minutes. The account's index limit (600 requests per 15 minutes) was already used up, for example by another window indexing a large project. Wait 15 minutes, then press **Try again**. ### No files could be indexed. This is not a result about your codebase. Every file DebugAI tried failed. That points at the connection or the server, not at your code. Check that this machine can reach DebugAI (see [Behind a proxy or firewall](/troubleshooting/sign-in#behind-a-proxy-or-firewall)), then press **Try again**. ### No files were indexed. Nothing failed and nothing was stored. Either every file found was one DebugAI never keeps, or the project is already at the free plan's 200 files, so nothing new fits. ### DebugAI found no files to index in this workspace. The open folder holds no file DebugAI indexes. It takes source files ending in `.js`, `.jsx`, `.ts`, `.tsx`, `.py`, `.mjs`, `.cjs`, `.java` and `.cs`, plus config files such as `package.json`, `tsconfig.json`, `pyproject.toml`, `requirements.txt`, `Dockerfile` and `go.mod`. Open the folder that holds your code, not a parent folder with only notes in it. ### DebugAI could not search this workspace for files, so nothing was indexed. VS Code's own file search failed, so DebugAI had no list of files to send. Run **DebugAI: Index Entire Workspace** again. If it keeps happening, write to support@debugai.io. ## A file is missing from the index Some files are never indexed, by design: - `.env` and every file like it (`.env.local`, `staging.env` and so on). - Key and certificate files: `.pem`, `.key`, `.pfx`, `.p12`, `.jks`, `.keystore`, `.ppk`, `.asc`, `.gpg`, `.kdbx`, `.crt`, `.cer`, `.der`, `.cert`, `.secret`. - Files whose whole name is a credentials word, such as `secrets.py`, `credentials.ts` or `password.js`. - `appsettings*.json`, Docker Compose files, lock files, minified `.min.js` and `.min.css` files, and `.map` files. - Anything inside `node_modules`, `dist`, `build`, `out`, `.git`, `__pycache__`, `.venv`, `venv`, `env`, `.next`, `.nuxt`, `coverage`, `site-packages`, `dist-packages`, `.tox`, `.pytest_cache`, `eggs`, `.eggs`, `.terraform`, `secrets`, `.secrets`, `.ssh`, `.gnupg`, `.aws`, `.azure`, `.kube`, `.docker` or a folder named `.env`. Folders are judged by their path inside your workspace. A project that itself sits under a folder called `build` still indexes. A folder called `build` inside your workspace does not. Files are cut at 50 KB. The rest of a longer file is not sent. ## Indexing one file **DebugAI: Index Current File** sends the file open in the editor. With no file open, it does nothing. ### File indexed. Nothing is wrong. ### This file is queued and will index on the next run, in about 15 minutes. The account's index limit is used up for now. Run **DebugAI: Index Current File** again in about 15 minutes. ### Could not index this file. The request failed. Run the command again. ### This file was not indexed. Secret files are never indexed, and free plans cap the project at 200 files. Either the file is one DebugAI never keeps (see the list above), or the project is already at the free plan's 200 files. ## Check Index Status ### No workspace open. Open a folder to begin indexing. DebugAI indexes a folder, not loose files. Use **File > Open Folder**. ### Set your API key to start indexing. Run "DebugAI: Set API Key" from the command palette. You are not signed in. Run **DebugAI: Sign In**. ### Indexing in progress (n/t files, p%)... A run is going. The status bar shows the same percentage. ### N files indexed. Ready for errors. Nothing is wrong. ### DebugAI has not indexed this workspace in this window yet. Run "DebugAI: Index Entire Workspace" to index it now. **Check Index Status** only knows what happened in this window. An index from an earlier session is still on the server. Run **DebugAI: Index Entire Workspace** if you want to be sure it is current. ## Nothing happened when VS Code started Automatic indexing runs when VS Code starts, and only when all of these hold: - You are signed in, and you were signed in when VS Code started. The first index after a new sign-in does not start on its own: press **Index workspace** on the **DebugAI connected** message, or run **DebugAI: Index Entire Workspace**. - The `debugai.autoIndex` setting is on (it is by default). - No full index of this project finished in the last 15 minutes. If one did, the automatic run is skipped without a message. A command you run yourself always runs. ## Answers still say DebugAI could not see your code If an answer reads **Insufficient context for specific fix** after you indexed, see [Answers and limits](/troubleshooting/answers#insufficient-context). It says which of several reasons applied. # MCP server problems Source: https://docs.debugai.io/troubleshooting/mcp Run doctor first, then find the message it printed or the one your agent passed on. ## Start with doctor ```bash npx -y @debugai/mcp doctor ``` It prints four sections: | Section | What it checks | | --- | --- | | **Runtime** | Your Node.js version | | **Account** | A key is stored and starts with `dbg_`. On macOS and Linux, that only you can read its file | | **API** | The DebugAI API accepts the key | | **MCP clients** | Each client on this machine has a DebugAI entry, for every folder and not one, running `@debugai/mcp@latest`, with no key written into it | It ends with `✓ Everything checks out.` or the number of problems to fix. To see which key is in use and whose account it is, run: ```bash npx -y @debugai/mcp status ``` Each heading below is a message as DebugAI prints it. `` stands for a client's name, such as Cursor. ## What doctor says ### Node N is too old The MCP server needs Node.js 18.14.1 or newer. Install a current Node.js LTS release, check it with `node -v`, and run `npx -y @debugai/mcp setup` again. ### No API key found You have not signed in on this machine. Run: ```bash npx -y @debugai/mcp login ``` ### Key does not look like a DebugAI key The key in use does not start with `dbg_`. If you set `DEBUGAI_API_KEY` in your environment, that value wins over the stored key, so check it first. Otherwise run `npx -y @debugai/mcp login --force`. ### Config file is readable by other users On macOS and Linux, the file that holds your key should be readable by you alone. Doctor prints the fix: ```bash chmod 600 ~/.debugai/config.json ``` ### Could not authenticate against the API Either your key was rotated, or the API cannot be reached from this machine. For a rotated key, run `npx -y @debugai/mcp login --force`. For the network, see [Could not reach the DebugAI API](#cannot-reach-api). ### ` — installed but DebugAI is not in its config` The client is on this machine but has no DebugAI entry. Doctor prints the command, for example: ```bash npx -y @debugai/mcp install --client=cursor ``` ### ` — debugai configured for ONE directory only` DebugAI works in one folder only. `claude mcp add` does this by default, because it adds a server for the current directory. To use DebugAI in every project, run: ```bash npx -y @debugai/mcp install --client=claude-code ``` ### ` — runs "@debugai/mcp" without a version` Without a version, `npx` runs the first copy it finds, and an old global install wins over the newest release. `npx -y @debugai/mcp install --client=` rewrites the entry with `@debugai/mcp@latest`. ### ` — pinned to ; newer releases will not reach it until you change that.` Only a note. The entry names one version on purpose, so updates do not reach it. Run `install --client=` if you want `@latest` back. ### ` — an API key is written in plain text in its config` The DebugAI entry in that client's config carries `DEBUGAI_API_KEY` in an `env` block. It works, but that key outranks the one `login` stores, so after you rotate your key this client keeps failing. It is also a key in a file that gets committed and shared. Run `npx -y @debugai/mcp login`, then delete the `env` block from the `debugai` entry in the file doctor names. ### `VS Code (native MCP) — no entry here, which is right with the DebugAI extension installed` Only a note. The DebugAI extension registers the server in VS Code itself, so no entry is needed. See [VS Code agent mode](/agents/vscode-agent-mode). ### None detected. Doctor found no MCP client on this machine. `npx -y @debugai/mcp install --list` shows every client DebugAI knows and where it looks for each. ## What install says `install` (and `setup`, which runs it) writes to the clients it finds. A client counts as found when its config file or its app folder exists. To write one that was not found, name it: `--client=` writes the entry anyway. The ids are `claude-code`, `claude-desktop`, `cursor`, `windsurf`, `zed`, `gemini-cli`, `cline` and `vscode`. Before changing a file, `install` copies it to a backup next to it, named `.debugai-backup-