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.
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.
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.
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:
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.
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,distand.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:
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.
Windows
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.
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.
Next
- MCP tools reference, every input and output field.
- Error memory, how a fix becomes "confirmed".
- The server will not connect: MCP troubleshooting.