open-source product · CLI + MCP · Apache-2.0
whatbrokegit-anchored crash context and verified fixes for AI coding agents
tldr
whatbroke is a zero-config, local-only capture layer for local crashes. You wrap a command you already run (npx @whatbroke/whatbroke run -- npm test). On a passing run it is invisible and records the commit as “green”; on a crash it writes a redacted, git-anchored bundle, ranks the suspect files with no LLM, and serves them to your coding agent over a read-only MCP server. After the agent edits, the verify_fix tool re-runs the exact captured command and reports fixed, same-failure, or different-failure, so it closes the loop instead of only packaging the crash. No account, no network, no dashboard.
install
npx @whatbroke/whatbroke run -- npm test # wrap any dev command npx @whatbroke/whatbroke verify # re-run the captured command: fixed / same-failure / different-failure npx @whatbroke/whatbroke mcp # start the read-only MCP server for your agent npx @whatbroke/whatbroke show # print the latest redacted bundle npx @whatbroke/whatbroke doctor # check your setup
how it works
The pipeline is crash → capture → git-anchored context → deterministic suspect ranking → redaction gate → MCP → verified fix.
Every time the wrapped command passes, whatbroke records the current commit as “green” in a local journal, keyed by the normalized command and branch. When the command fails, it intersects the files on the crash stack trace with the files changed since that last green commit and scores them with fixed integer weights, no LLM: a file both on the crash path and changed since green ranks highest, each suspect carrying explicit reasons, and a one-hop import signal extends the set to close neighbors. That is the moat: accumulated local ground truth a SaaS monitor cannot see and an LLM cannot reproduce from a prompt.
The ranking is measured, not asserted: top-1 suspect accuracy is 90.3% and top-3 accuracy is 100% over 31 scored cases drawn from 35 real regression scenarios, replayed on every PR with npm run bench and CI failing if top-3 drops below baseline.
After your agent edits, the verify_fix tool re-runs the exact captured command and reports one of fixed, same-failure, or different-failure, handing back a fresh bundle to iterate on, so whatbroke closes the loop rather than only packaging the crash.
Before anything leaves the process, a mandatory fail-closed redaction gate scrubs secrets: only redacted bundles ever touch disk, and a redaction report lists what was scrubbed. Node and TypeScript are first-class, and an adapter layer adds Python (pytest) and Go (go test) with ranked suspects, crash-kind classification, the diff, and full logs. The primary surface is a read-only, stdio MCP server exposing get_suspects, get_diff_vs_green, get_logs, get_history, and verify_fix; the same bundle can also open as a prefilled GitHub issue, print in the terminal, or post from a composite GitHub Action (sticky PR comment, uploaded artifact, job summary, cached green baseline). Everything is deterministic: an optional --explain LLM narration is off by default and can never change the suspects or their confidence.
vs the alternatives
| whatbroke | raw stack trace | Sentry | git bisect | |
|---|---|---|---|---|
| Where it runs | Local terminal | Local terminal | Production | Local terminal |
| Names the file | Yes, ranked | Sometimes | Yes (prod errors) | Finds commit, not file |
| Uses git history | Diff since last green | No | Release tags | Bisects commits |
| Verifies the fix | Yes, re-runs the command | No | No | No |
| Agent-ready (MCP) | Yes | No | No | No |
| Secrets scrubbed | Mandatory gate | No | Configurable | n/a |
| Deterministic | Yes, no LLM | n/a | n/a | Yes |
faq
How does deterministic bug ranking work without an LLM?
whatbroke intersects the files on the crash stack trace with the files changed since the last green commit (the last passing run of the same command), scores them with fixed integer weights, and extends the set with a one-hop import signal. Files both on the crash path and changed since green rank highest, each with explicit reasons. There is no model call and no randomness: the same crash produces byte-identical output. It is measured too, at 90.3% top-1 and 100% top-3 suspect accuracy over 31 scored cases from 35 real regression scenarios replayed in CI.
What is the verified-fix loop?
After your agent edits the code, whatbroke's verify_fix MCP tool (or the verify command) re-runs the exact command that was captured and reports one of three outcomes: fixed, same-failure, or different-failure. A different failure hands back a fresh bundle to iterate on, so the tool closes the loop instead of only packaging the original crash.
Does it work with Claude Code and Cursor?
Yes. whatbroke runs a local read-only MCP server, so any MCP-aware coding agent (Claude Code, Cursor, and others) can pull the ranked suspects, the diff since the last green commit, the redacted logs, the history, and verify_fix directly into context. The same bundle can also open as a prefilled GitHub issue, print in the terminal, or post from a GitHub Action in CI.
What languages does it support?
Node and TypeScript are first-class. Python (pytest) and Go (go test) are supported through an adapter layer that produces ranked suspects, crash-kind classification, the diff, and full logs, with stack frames parsed from stderr tracebacks and panics for commands like python app.py or go run. More adapters can extend it further.
Is whatbroke a replacement for Sentry?
No. Sentry monitors production; whatbroke captures the local terminal crash: the test or server that died in your shell before anything shipped. They are complementary and fill different gaps.
npm
Live npm stats: refreshed a few times a day.
481 total downloads
- 481downloads
more projects
Klinder-OSS · AHTML · Diffcore · Roy UI · Fresco · all work · about the maker
Built by Dibbayajyoti Roy. Questions or want to use it? Get in touch.