Claude Code

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.

npx -y @debugai/mcp setup

npx -y @debugai/mcp login
npx -y @debugai/mcp install --client=claude-code

✓ Claude Code — debugai configured

Use the debugai lookup_error tool on this error: TypeError: Cannot read properties of undefined (reading 'name')

Make Claude reach for itCopy Anchor Link

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:

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 hookCopy Anchor Link

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:

{
  "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/<name>). 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:

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 beforeCopy Anchor Link

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:

! 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:

claude mcp add --scope user debugai -- npx -y @debugai/mcp@latest

The config it writesCopy Anchor Link

setup adds one entry to the top-level mcpServers in ~/.claude.json. On Windows, ~ is your user folder, C:\Users\<you>.

{
  "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-<timestamp>. 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.

NextCopy Anchor Link

• Work with your agent: the lookup, debug and report loop, and how to point an answer at the right project.
• MCP server troubleshooting: doctor output, sign-in from inside a chat, and the errors an agent can get back.