# Predictive Debugger documentation > An MCP server that finds likely runtime failures in JavaScript and TypeScript. > Generated from https://predictivedebugger.dev/docs. --- # Quickstart > Install the MCP server, confirm your agent can see it, and run your first risk scan in about five minutes. Source: https://predictivedebugger.dev/docs/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. ```bash # 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: ```bash 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. ```text 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: ```json { "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: ```text 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](/docs/guides/review-new-code) - the case the server was built for. - [Find the riskiest file before a release](/docs/guides/find-risk) - how to read a scan properly. - [Trace what a change breaks](/docs/guides/trace-impact) - 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. --- # Review code your agent just wrote > Check a change from outside the context that produced it, using a fresh prediction for one file or a scoped sub-agent for several. Source: https://predictivedebugger.dev/docs/guides/review-new-code The weakest review available is the one where an agent re-reads its own work in the same conversation. The reasoning that made the code look right is still in scope, and it tends to confirm itself. This is the case Predictive Debugger was built for: getting a second opinion from outside that context. ## The rule the server actually enforces The MCP server ships instructions that ask your agent to check new code from a fresh context. What it asks for depends on how far the change reaches - and the test is **file count**, not how large the change felt or whether it was a fix or a feature. | Change | Requested check | | ----------------------------------------------- | --------------------------------------- | | One file, including a whole feature in one file | A fresh `predict_failures` call | | Several files | A sub-agent scoped to the changed files | | Mechanical correction with one clear answer | Neither | The reason for the split: `predict_failures` reads each file on its own. It never sees how several files have to agree, so it cannot catch a contract that two files disagree about. ## One file Ask directly: ```text Check src/services/orders.ts for likely runtime failures. ``` This calls a model, and the verdict comes back with a line number and a reason rather than a vague warning. A real finding from the demo project: ```json { "pattern": "race_condition", "file": "reserveStock.ts", "line": 26, "score": 0.82, "reason": "onHand is read at line 18 before two awaits; concurrent reserveStock calls for the same sku both read the same onHand and setStock(sku, onHand-qty) overwrites each other, letting stock oversell despite the negative-stock guard." } ``` Read the reason, not the score. The number is a confidence from that one recorded prediction, not a measured accuracy rate. The reason is what you can check against the code - and here it names the exact mechanism, which makes it falsifiable. ## Several files Do not loop `predict_failures` over each file and call it a review. Scope a sub-agent to the change instead: ```text Review the changes I just made to src/services/orders.ts, src/services/stock.ts and src/db/inventory.ts. I was adding partial-reservation support. Review only that change. ``` Giving it the files _and_ the intent matters. An unscoped agent rebuilds the project from cold and reports on code nobody touched, which is what makes this expensive and noisy. ## Reviewing a batch efficiently If you do want per-file verdicts on several files, pass them in one call rather than one at a time: ```text Check src/services/orders.ts, src/services/stock.ts and src/db/inventory.ts for likely runtime failures. ``` The verdicts are independent and run concurrently, so a batch costs the same as the same files one at a time but returns in roughly the time of the slowest one. Calling once per file pays that wait again for every file. ## A clean verdict is not a clearance `predict_failures` returning nothing means the file is locally sound. It does not mean the feature is correct, that the files agree with each other, or that the behavior matches what you intended. Those still need tests and your own reading. --- # Find the riskiest file before a release > Rank a directory by risk density, read the signals behind the ranking, and understand what the numbers do and do not claim. Source: https://predictivedebugger.dev/docs/guides/find-risk Before a release you want to know where to spend your reading time. A scan answers that in a second, locally, with no model call. ```text Use Predictive Debugger to find the riskiest files in src/. ``` ## A real ranking This is an actual scan of the Predictive Debugger source tree, trimmed to the top four: ```json { "scanned": 28, "excludedTests": 13, "orderedBy": "riskDensity", "files": [ { "file": "core/analysis/dependencies.ts", "riskDensity": 0.53, "riskScore": 0.77, "lines": 282 }, { "file": "core/analysis/modulePaths.ts", "riskDensity": 0.51, "riskScore": 0.47, "lines": 83 }, { "file": "core/prediction/predictFile.ts", "riskDensity": 0.45, "riskScore": 0.39, "lines": 125 }, { "file": "core/analysis/callees.ts", "riskDensity": 0.36, "riskScore": 0.8, "lines": 522 } ] } ``` ## Density and score are different questions Look at the first and last rows. `callees.ts` has the **highest risk score** (0.80) but nearly the **lowest density** (0.36). `dependencies.ts` is the reverse. - **`riskDensity`** - how concentrated the risk is, per line. This is what the ranking sorts by, because it answers "where is reading time best spent?" - **`riskScore`** - the total amount of structural risk in the file. A 522-line file accumulates a lot of it simply by being long. `callees.ts` is big, so it scores high overall. `dependencies.ts` packs more risk into half the lines, so it ranks first. Sorting by score alone would just rank your longest files. ## Read the signals, not the number Ask for the detail behind a row: ```text What are the risk signals in src/core/analysis/dependencies.ts? ``` ```json { "metrics": { "functions": 23, "longFunctions": 1, "branches": 53, "asyncCalls": 15, "nestedLoops": 3, "mutations": 19, "tryCatch": 3, "cyclomatic": 64, "lines": 282 }, "riskScore": 0.767, "riskDensity": 0.53 } ``` The combination that matters here is **15 async boundaries and 19 mutations of existing state in one file**. That is the shape a race condition takes: state read before an `await` and written after it. Three nested loops and a cyclomatic complexity of 64 mean many paths through that state. None of that proves a bug exists. It tells you what kind of bug this file is built to hide, which is what to look for when you read it. ## Tests are excluded on purpose Note `excludedTests: 13` - nearly a third of the tree was skipped. Test files rank high for a structural reason rather than a real one: mocked awaits read as async complexity. If you actually want to audit the complexity of the suite itself: ```text Scan src/ with Predictive Debugger and include test files. ``` ## Narrowing a large tree `scan_project` returns 50 files by default and up to 500. On a big repository, scan the directory you are about to touch rather than the root - a ranking of the whole monorepo is rarely the question you have. ## What the ranking does not mean Risk density is a reading priority, not a probability that a file contains a defect. A file at 0.53 is not "53% likely to be broken". A low-density file can still be wrong, and a high-density file can be perfectly correct and simply hard to change safely. --- # Trace what a change breaks > Find a file's imports, reverse imports, and connected tests with source-line evidence, so a local edit gets a review as wide as its reach. Source: https://predictivedebugger.dev/docs/guides/trace-impact A change to one file is rarely contained to one file. Before editing, find out who depends on it and which tests are connected. ```text Show the imports and tests connected to src/core/analysis/dependencies.ts. ``` This runs locally. No model call. ## A real map ```json { "file": "src/core/analysis/dependencies.ts", "depth": 1, "dependencies": [ { "file": "src/core/analysis/ast.ts", "via": [{ "line": 3, "kind": "import" }] }, { "file": "src/core/analysis/modulePaths.ts", "via": [{ "line": 4, "kind": "import" }] }, { "file": "src/core/analysis/moduleResolution.ts", "via": [{ "line": 5, "kind": "import" }] }, { "file": "src/core/sourceFiles.ts", "via": [{ "line": 6, "kind": "import" }] } ], "dependents": [ { "file": "src/mcp/server.ts", "via": [{ "line": 6, "kind": "import" }] }, { "file": "src/test/dependencies.test.ts", "test": true, "via": [{ "line": 6, "kind": "import" }] } ], "totalNeighbors": 6, "truncated": false } ``` Three things to read here: - **`dependencies`** - what this file pulls in. Change these and you may change this file's behavior. - **`dependents`** - what pulls this file in. These are what your edit can break. Here it is exactly one production file, `src/mcp/server.ts`, so the blast radius is small. - **`test: true`** - `src/test/dependencies.test.ts` is the suite connected to this file. That is the one to run first. Every relationship carries a `line`, so you can jump straight to the import rather than searching for it. ## Evidence, not coverage `test: true` means that file imports this one and sits at a test path. It does **not** mean the test covers the code you are about to change, and the map shows static imports only - not runtime calls, dynamic `import()` resolved at runtime, or dependency injection. A file with no listed dependents can still be reached. ## Going wider Default depth is one hop each way. For a change you expect to ripple: ```text Map the dependencies of src/core/analysis/dependencies.ts two hops out. ``` Depth goes up to 3. Raise it deliberately - each hop multiplies the neighbors, and `limit` (50 by default, 200 max) will start truncating. Check `truncated` in the result before treating a map as complete. ## Unresolved imports are reported, not hidden ```json "unresolved": [ { "line": 1, "specifier": "fs/promises", "reason": "external, out-of-root or unresolved import" }, { "line": 2, "specifier": "path", "reason": "external, out-of-root or unresolved import" } ] ``` These are Node built-ins, so they are correctly outside the map. The field exists so you can tell "nothing depends on this" apart from "the scan could not follow the import" - if a specifier you expected to resolve shows up here, the map is incomplete and you should know that before trusting it. ## Pairing it with a review The useful sequence before touching a shared file: ```text Show the imports and tests connected to src/core/analysis/dependencies.ts. ``` then, after your edit, ```text Check src/core/analysis/dependencies.ts and src/mcp/server.ts for likely runtime failures. ``` Reviewing the file you changed together with its dependents is what turns a local edit into a review as wide as the change actually reaches. --- # Advanced setup > Provider login, registration scope, Codex and Copilot configuration, updates, and building Predictive Debugger from source. Source: https://predictivedebugger.dev/docs/setup The [quick setup](https://github.com/SpeedosDK/predictive-debugger#setup) uses the published npm package. This page covers provider login, registration scope, updates and source builds. ## Provider login For predictions, install and sign in to at least one supported CLI: ```bash npm i -g @anthropic-ai/claude-code # then: claude npm i -g @openai/codex # then: codex login npm i -g @github/copilot # then: copilot, and /login ``` Static analysis and dependency maps need no provider login. Log analysis also runs locally and requires Python 3. Set `PYTHON_PATH` in the MCP server's environment if Python cannot be found automatically. ## Ask your agent to configure it Open the project where you want to use Predictive Debugger and ask: > Add Predictive Debugger as a project-scoped MCP server. Use `npx` with arguments > `-y predictive-debugger@latest`. On native Windows, use `cmd` with arguments > `/d /c npx -y predictive-debugger@latest`. Verify that it starts and lists its tools. For every project, replace "project-scoped" with "user-level". If your agent cannot edit its own configuration, use the [manual setup](https://github.com/SpeedosDK/predictive-debugger#setup). Scope determines where the MCP registration loads. It does not restrict which files the server process can read. Project entries can override user-level entries with the same name. ## Codex project configuration Add this to `.codex/config.toml` inside a trusted project: ```toml [mcp_servers.predictive-debugger] command = "npx" args = ["-y", "predictive-debugger@latest"] startup_timeout_sec = 60 ``` On native Windows, use `command = "cmd"` and `args = ["/d", "/c", "npx", "-y", "predictive-debugger@latest"]`. Use `~/.codex/config.toml` for every project. The startup timeout allows time for the first package download; it can also be added to an entry created by `codex mcp add`. Restart Codex and check `/mcp`. See [Codex MCP configuration](https://developers.openai.com/codex/mcp/). ## Copilot user-level setup On macOS, Linux or WSL: ```bash copilot mcp add predictive-debugger -- npx -y predictive-debugger@latest ``` On native Windows, from PowerShell: ```powershell copilot mcp add predictive-debugger -- cmd /d /c npx -y predictive-debugger@latest ``` Restart Copilot and check `/mcp`. See [Copilot CLI MCP configuration](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference#mcp-server-configuration). For Claude Code, the [quick setup](https://github.com/SpeedosDK/predictive-debugger#setup) supports `--scope project` and `--scope user`; see [Claude Code's MCP docs](https://code.claude.com/docs/en/mcp). ## Updating Configurations using `@latest` resolve the current npm release when the agent starts the server. Restart the agent or reconnect its MCP server to use an update. A running server keeps its current version. To force a metadata refresh and print the downloaded version: ```bash npx --prefer-online -y predictive-debugger@latest --version ``` Then restart your agent. For controlled updates, replace `@latest` in your configuration with a published version such as `@0.8.0`. See [npm's cache options](https://docs.npmjs.com/cli/v11/commands/npm-exec/#a-note-on-caching). ## Build from source Download and extract **Source code (zip)** from the [latest release](https://github.com/SpeedosDK/predictive-debugger/releases/latest), or clone the repository: ```bash git clone https://github.com/SpeedosDK/predictive-debugger.git cd predictive-debugger npm ci npm run build ``` For an extracted ZIP, run the last two commands in the extracted folder. | Output | Purpose | | -------------------- | ------------------------- | | `dist/mcp-server.js` | MCP server | | `dist/extension.js` | VS Code extension preview | Build and test commands for contributors are in [CONTRIBUTING.md](https://github.com/SpeedosDK/predictive-debugger/blob/master/CONTRIBUTING.md). ## Using a local build Configure the server command as `node` with the absolute path to `dist/mcp-server.js` as its only argument. For example: ```bash claude mcp add --scope project predictive-debugger -- node "/absolute/path/to/predictive-debugger/dist/mcp-server.js" ``` Keep the checkout in a permanent location, since moving it breaks that path. The repository's `.mcp.json` already uses `node ./dist/mcp-server.js`, so Claude Code and Copilot use the local build when started here. To switch a registration to npm, replace its command and arguments with the `npx` setup. ## Troubleshooting | Symptom | Check | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | First connection times out | Run the version command once to download the package. In Codex, allow a 60-second startup timeout. | | Windows cannot start `npx` | Use `cmd /d /c npx` as shown in the quick setup. | | No provider is available | Ask the agent to call `list_providers`, then run the chosen CLI directly and sign in. | | Sign-in is reported but prediction fails | Some credential-store checks are provisional. Run the CLI directly to verify live access. | | Server appears to hang in a terminal | With no arguments, it waits for MCP messages over stdio. Use `--version` or `--help` for a terminal check. | | An older version still runs | Restart the agent and check for a project registration overriding your user-level configuration. | | Log analysis is unavailable | Install Python 3 or set `PYTHON_PATH` in the MCP server environment. | --- # Tool reference > Parameters, outputs, and limits for all six Predictive Debugger MCP tools, and how the prediction score is calculated. Source: https://predictivedebugger.dev/docs/tools The MCP server exposes six tools. Static analysis, dependency mapping and log analysis run locally. Only `predict_failures` calls a model provider. Source analysis supports `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts` and `.cts`, including decorators. Vue and Svelte single-file components are excluded. Files above 4 MB are rejected. Use absolute paths unless a parameter says otherwise. ## `scan_project` Rank a directory's source files by `riskDensity`, the concentration of structural risk signals per line. This helps choose where to read first; it does not report confirmed defects. | Parameter | Default | Purpose | | -------------- | -------- | --------------------------------- | | `directory` | Required | Directory to scan | | `limit` | `50` | Maximum results, up to 500 | | `includeTests` | `false` | Include test files in the ranking | | `verbose` | `false` | Include raw metric counts | Results include `scanned`, `returned`, `orderedBy` and ranked `files`. Paths are relative to the scanned directory. Unreadable files are reported separately so one failure does not discard the rest of the scan. Tests are excluded by default because mocked awaits and other test structures can rank highly without indicating production risk. Set `includeTests: true` when reviewing the test suite itself. ## `analyze_file` Pass `file` to get AST complexity metrics, `riskScore`, `riskDensity` and the signals behind the scores. A parse failure returns `parseError` and a zero score; that zero is not evidence that the file is safe. ## `map_dependencies` Find a file's imports, reverse imports and tests connected through imports. Each relationship has a `via` chain with paths, import kinds and source lines. These are static file relationships; they do not establish runtime callers or test execution coverage. | Parameter | Default | Purpose | | ----------- | -------- | ------------------------------------------------ | | `directory` | Required | Project directory; outside source is excluded | | `file` | Required | Source file, absolute or relative to `directory` | | `depth` | `1` | Import hops in each direction, from 1 to 3 | | `limit` | `50` | Total neighbors across both lists, up to 200 | | `maxFiles` | `1000` | Maximum discovered source files, up to 2,000 | The map includes tests and follows ESM imports and re-exports, type import expressions and literal dynamic imports. `test: true` follows test-path naming conventions. CommonJS requires, import assignments and nonliteral dynamic imports remain unresolved. Build, vendor and hidden directories are excluded. The index refreshes on every request. Work is bounded by 20,000 directory entries, 64 directory levels, 4 MB per source file, 32 MB of source reads and 10,000 import references. Serialized replies are capped at 32,000 characters. | Field | Meaning | | ---------------------- | --------------------------------------------------- | | `unresolved` | Unresolved outgoing imports from the requested file | | `coverage.unresolved` | Unresolved references across the scanned project | | `issues` | Read and parse failures, plus scan-limit details | | `coverage.scanLimited` | The scan reached a discovery or processing limit | | `truncated` | Some reply entries were omitted | A missing relationship in a partial scan is not proof of absence. The tool uses no model calls, but its replies occupy the calling agent's context. See the [local measurements](https://github.com/SpeedosDK/predictive-debugger/blob/master/bench/DEPENDENCY-MAP-CHECKPOINT.md). ## `analyze_logs` Pass `logFile` to score log lines by severity and unusual wording, returning the anomalies first. Optional `threshold` ranges from 0 to 1 and defaults to `0.5`. Requires Python 3; see [setup](/docs/setup#provider-login). ## `predict_failures` Combine static analysis with an independent verdict from a supported CLI's model. Each file requires a model call and uses the provider's usage allowance. | Parameter | Default | Purpose | | --------------- | ----------------------------------- | ------------------------------------------------------------- | | `file` | Required unless `files` is supplied | One source file | | `files` | None | Non-empty batch of source paths; takes precedence over `file` | | `concurrency` | `4` | Concurrent batch predictions, from 1 to 8 | | `provider` | First installed CLI | `claude`, `codex` or `copilot` | | `model` | CLI default | Model override passed to the provider | | `calleeContext` | `true` | Include bounded imported definitions and referenced types | | `multi` | `false` | Request all demonstrable findings; experimental | | `logFile` | None | Log file to include in the combined score | | `verbose` | `false` | Include static metrics and the full log breakdown | Use `files` for a change set. Predictions run concurrently, with duplicate resolved paths removed. The reply contains `results` in input order and lists individual `failures` separately. A batch still makes one model call per unique file; lower `concurrency` if the provider starts rate-limiting. ### Reading a verdict The reply includes `pattern`, `score`, `line`, `reason`, `status` and `actionable`. Use `actionable` when deciding whether to present a prediction as a defect. | `status` | Meaning | | ------------- | ----------------------------------------------------- | | `actionable` | A reported defect has a model score of at least `0.7` | | `uncertain` | A possible defect falls below the reporting threshold | | `none` | No defect reported | | `unavailable` | No usable model verdict; this is not a clean result | `checked` lists the bug categories the model says it considered. It is a self-report, and an empty list means no coverage was reported. Additional findings appear in `findings` when returned. The reporting threshold was measured on single-finding replies, so `multi: true` is less well characterized. Large files send at most 120,000 source characters, selected as whole declarations with original line numbers. The reply discloses truncation; omitted code remains unreviewed. There is no automatic second model pass. ### Dependency context By default, the model also receives bounded supporting definitions from local dependencies. Set `calleeContext: false` to send only the source file. Third-party packages are never read for this context. Supported cases include direct ESM imports, declared imported objects, referenced types, imported constructors, named/default binding re-exports and unambiguous `export *` barrels through at most four files. Local `tsconfig.json` path mappings support relative config inheritance. CommonJS exports, namespace re-exports, package-based config inheritance and injected instance methods remain unresolved. Conflicting or unreadable wildcard branches remain unknown. Each collection parses at most 24 dependency files, each no larger than 4 MB. Each requested export has a 128-step traversal limit, including cached paths. The text budget follows source length, with a 1,000-character minimum and 16,000-character maximum. It includes at most 12 definitions of 3,000 characters each. Oversized imported objects and static class members prioritize the called member, referenced fields and helpers. Retained members stay in source order, and omissions are marked. Dynamic definitions, duplicate overrides, inheritance and decorators retain prefix truncation. This does not establish complete state flow through the program. ### Reviewing code an agent just wrote The server advertises the [review routing](https://github.com/SpeedosDK/predictive-debugger#tools) in MCP `instructions` and repeats a short reminder in each prediction's `review` field. Some clients do not forward server instructions, so the result also carries it. For changes spanning files, a sub-agent should receive the changed files and intended behavior, review only that scope, and run in the background where the host supports it. The sub-agent rule's benefit has not been measured. A clean per-file prediction cannot establish that the feature meets its requirements. ## `list_providers` Takes no parameters. Reports installed supported CLIs and their sign-in checks. Some credential-store checks are provisional; a live CLI call confirms access. ## How the score works `riskScore` measures accumulated structural signals such as nested loops, long functions and async boundaries. `riskDensity` adjusts for file length and reduces the influence of signals that accumulate with it. `scan_project` sorts by density. Both scores use smooth saturation to stay within 0 to 1 without flattening every complex file to the same maximum. `combinedScore` is a separate blend used by the prediction pipeline: | Input | Weight | | ----------------------------- | ---------------------------------------------------- | | Model verdict | `0.90` without logs | | Static risk | `0.10` without logs | | Log anomalies, when available | `0.15`; the other weights are scaled to total `0.85` | The model verdict dominates. The `actionable` gate uses the model's score, not `combinedScore`. The implementation is in [`score.ts`](https://github.com/SpeedosDK/predictive-debugger/blob/master/src/core/prediction/score.ts) and [`confidence.ts`](https://github.com/SpeedosDK/predictive-debugger/blob/master/src/core/prediction/confidence.ts). See [benchmark results](https://github.com/SpeedosDK/predictive-debugger/blob/master/bench/RESULTS.md) for measurements and their limits. --- # VS Code preview > Run the experimental Predictive Debugger VS Code extension from source and configure its settings. Source: https://predictivedebugger.dev/docs/vscode The extension is unfinished. It is not published to the VS Code Marketplace and no prebuilt VSIX is distributed. ## Try it from source 1. [Build the project](/docs/setup#build-from-source). 2. Open the Predictive Debugger folder in VS Code. 3. Press F5 to launch an Extension Development Host. 4. Run `Predictive Debugger: Connect` in the new window to choose a CLI and verify its sign-in. 5. Run a prediction command below. | Command | What it does | | ------------------------------------------------------- | ---------------------------------------------------------- | | `Predictive Debugger: Connect` | Pick a CLI and verify live access | | `Predictive Debugger: Predict Failures in Current File` | Analyze the open file | | `Predictive Debugger: Predict Failures Across Project` | Analyze source files across the workspace, including tests | Results appear in the Problems panel and **Output > Predictive Debugger**. The extension requires a trusted workspace. Use the **Run Extension (bug-patterns test folder)** launch configuration to try the project-wide command. Its development host opens a separate fixture folder, since VS Code cannot open the same folder in both windows. ## Settings These are VS Code extension settings. For MCP predictions, pass the [tool parameters](/docs/tools#predict_failures) instead. | Setting | Default | Purpose | | ------------------------------------- | ----------- | --------------------------------------------------------- | | `predictiveDebugger.claudeModel` | CLI default | Model alias for Claude | | `predictiveDebugger.codexModel` | CLI default | Model for Codex | | `predictiveDebugger.copilotModel` | CLI default | Model for Copilot; `auto` lets the CLI choose | | `predictiveDebugger.logFile` | None | Workspace-relative log file to include in the score | | `predictiveDebugger.pythonPath` | Auto-detect | Python interpreter for log analysis; machine-scoped | | `predictiveDebugger.multipleFindings` | `false` | Request all demonstrable failures in a file; experimental | | `predictiveDebugger.maxFiles` | `25` | Maximum files per project run; each requires a model call | For watch mode, testing and packaging, see [CONTRIBUTING.md](https://github.com/SpeedosDK/predictive-debugger/blob/master/CONTRIBUTING.md).