Quickstart

Predictive Debugger is an MCP server. You do not run it directly - you add it to a coding agent you already use, then ask that agent questions about your code.

1. Add the server

Pick the CLI you already sign in to. Run this from the project you want to review.

# Claude Code
claude mcp add --scope project predictive-debugger -- npx -y predictive-debugger@latest

# Codex
codex mcp add predictive-debugger -- npx -y predictive-debugger@latest

# GitHub Copilot
copilot mcp add predictive-debugger -- npx -y predictive-debugger@latest

On native Windows, replace npx with cmd /d /c npx.

You need Node.js 22 or later. No API key, no account, no configuration file.

2. Confirm the connection

Restart your agent, then check its MCP list - /mcp in Claude Code - for predictive-debugger and its six tools.

To check the package downloads at all, independently of any agent:

npx -y predictive-debugger@latest --version

Without --version that command starts a stdio server and appears to hang. That is correct: it is waiting for an agent to talk to it. Press Ctrl+C.

3. Ask a question

You never call the tools by name. You ask your agent in plain language, and it picks the tool.

Use Predictive Debugger to find the riskiest files in src/.

The scan is local and deterministic. Nothing is sent anywhere, and no model is called. On a real project the reply is a ranking:

{
  "scanned": 28,
  "returned": 8,
  "orderedBy": "riskDensity",
  "excludedTests": 13,
  "files": [
    {
      "file": "core/analysis/dependencies.ts",
      "riskDensity": 0.53,
      "riskScore": 0.77,
      "lines": 282,
      "signals": [
        "53 branch(es)",
        "19 mutation(s) of existing state",
        "15 async boundary/boundaries (await, timers)",
        "cyclomatic complexity 64",
        "3 nested loop(s)"
      ]
    },
    {
      "file": "core/analysis/modulePaths.ts",
      "riskDensity": 0.51,
      "riskScore": 0.47,
      "lines": 83,
      "signals": ["19 branch(es)", "cyclomatic complexity 21"]
    }
  ]
}

That is a reading order, not a defect list. dependencies.ts is not broken - it is the file where a bug would have the most room to hide, so it is the one worth your attention first.

4. Go deeper on what it found

Three follow-ups, in the order most reviews want them:

What are the risk signals in src/core/analysis/dependencies.ts?
Show the imports and tests connected to src/core/analysis/dependencies.ts.
Check src/core/analysis/dependencies.ts for likely runtime failures.

The first two stay local. Only the third calls a model, using your CLI’s sign-in and its allowance.

Where to go next

• Review code your agent just wrote - the case the server was built for.
• Find the riskiest file before a release - how to read a scan properly.
• Trace what a change breaks - imports, reverse imports, and connected tests.

What this is not

Risk scores and predictions can be wrong. A clean verdict on one file does not prove a feature works, and a high risk density does not mean a file contains a bug. Use the output to decide where to look, then confirm behavior with tests and your own reading.