News

The edit that looked perfect

A while back I watched an AI coding agent do something that every developer working with these tools will eventually recognize. It opened a file, found a retry loop with exponential backoff wrapped around a network call, and decided the whole thing was needless ceremony. Three nested lines became one clean call. The diff was small. The tests passed. The pull request was a genuine pleasure to read.

It also brought back an outage.

That loop was not decoration. Someone had added it eighteen months earlier, at two in the morning, after a flaky upstream API took down checkout for the better part of an hour. The backoff was the fix. The agent could not have known that, because nothing in the code said so. The function was named sensibly, the variables were clear, and the logic was correct in isolation. Everything about the code told you exactly what it did. Nothing told you why it was there.

And that is the uncomfortable part. Nobody in this story did anything wrong. The original author solved a real problem under pressure. The reviewer approved a clean, well-tested change. The agent followed its instructions and produced exactly the kind of tidy refactor we ask these tools for every day. Every individual step was defensible. The failure lived in the gaps between them, in reasoning that was perfectly clear to the people involved at the time and then quietly evaporated, because nothing in our workflow was built to keep it.

This is the quiet problem underneath the current wave of AI-assisted development. We have gotten very good at giving models the what: the syntax tree, the types, the call graph, the surrounding lines. Tools that index your codebase and feed the relevant snippets to an agent are genuinely useful, and they keep getting better. But they answer a question the agent was already halfway to answering on its own. The question that actually prevents damage is the one your code has never been able to hold on its own: why is this here, and what breaks if I remove it?

WhyGraph exists to answer that question. Before the edit, not in the post-mortem.

Why this keeps happening

Let me name it, because the industry already has: this is comprehension debt. Not the debt of messy code, but the debt of lost reasons. Every decision a team makes leaves a mark in the codebase, and almost none of the reasoning survives next to it.

Think about where the "why" of any given line actually lives. A little of it might be in a comment, if someone was disciplined that day. Some of it is in the commit that introduced it, assuming the commit message says more than "fix stuff." More of it is in the pull request discussion, where someone asked "do we really need the retry here?" and someone else explained. And a lot of it is in the issue that PR closed, three clicks away in a tracker most people never open while they are actually coding.

An AI agent editing your code sees none of that. It sees the file. Maybe, with a good context tool, it sees a handful of related files. It does not see the eighteen-month-old incident, the review comment, or the closed ticket. So it does the reasonable thing based on what it can see, which is exactly the problem. It is confident precisely because it is missing the context that would make a careful human pause.

An AI editor is only as safe as the context it is given, and the reason a line exists is almost never in the line.

This is what people are really pointing at when they talk about context engineering, or worry that vibe coding produces software nobody understands. The model is not dumb. It is under-informed, and it does not know that it is. Speed without the "why" is just a faster way to reintroduce old bugs.

Meet WhyGraph

So here is the idea. Your repository already recorded the reasons. They are sitting in your git history and your GitHub data right now: the commits that touched each line, the blame behind them, the pull requests that merged them, and the issues those PRs closed. The information exists. It is just scattered across four places and never assembled at the one moment it matters.

WhyGraph is a rationale layer over your codebase. It gathers that scattered evidence for any chunk of code and turns it into a structured rationale card: purpose, why, constraints, tradeoffs, and risks. When your AI editor is about to touch a function, it can ask WhyGraph for that card and get the reasoning back before it writes a line. The card is cached, so the second time anyone asks about the same piece of code, the answer comes back instantly.

Why should an agent rediscover the reasoning behind every line, slowly and imperfectly, when your repository already wrote it down? That is the whole pitch. WhyGraph does not try to make the model smarter. It just stops throwing away the context you already paid for.

And because it speaks MCP, the standard protocol these tools use to reach external sources, it is not welded to one editor. Any AI-powered tool that speaks MCP can ask it the same questions.

How it works, briefly

You do not need the internals to use it, but the shape is worth understanding, because one detail is what makes the rest trustworthy.

1. WhyGraph reads a graph of your code and joins it to your git and GitHub history. You do not wire this up by hand. You run whygraph scan and it builds the picture.
2. It describes each change from the raw git diff, not from the commit message. This is the part that matters. WhyGraph looks at what actually changed in the code and writes its own description of it. So when a developer commits eighty lines under the message "wip", WhyGraph still produces an honest account of what that commit did. Its record of your history does not depend on anyone writing good commit messages, which is fortunate, because we do not.
3. Before an edit, your editor calls WhyGraph's tools by name: whygraph_rationale_brief for the "why" card, whygraph_evidence_for for the raw receipts (the commits, PRs, and closed issues behind a piece of code), and whygraph_area_history for everything that ever touched a given path. The surface is deliberately narrow. It hands over reasons, not a general query console.
4. There is also a /whygraph-plan flow that spins up a planning agent with the relevant rationale cards already inlined, so the "why" is in front of it from the start rather than something it has to remember to go and look up.

Back to that retry loop. With WhyGraph in the loop, the agent's brief would have said something close to "added after a production incident; removing it brings the outage back." And the agent, now actually informed, leaves it alone. Same model, same task, one extra sentence of context, completely different outcome.

More than a pre-edit helper

Here is where it gets more interesting, and I want to be careful to separate what WhyGraph does today from where we are taking it.

What it does today: because every commit is described from the raw diff, WhyGraph ends up holding a trustworthy record of what actually changed in your codebase over time, independent of how good or bad the commit messages were. It already exposes a repository overview, the counts of commits, PRs, and issues, the date range of your history, your top contributors, and how much of that history has been described so far. It exposes the description of any individual commit. And because it ships as a single Docker image speaking MCP over stdio, any AI-powered application can query all of this, not only your code editor. The same layer that stops a bad edit is also a clean, ground-truth feed about your codebase that other tools can build on.

Where we are taking it: once every diff in your history carries an honest description, the questions you can start to ask get a lot more interesting. What actually shipped this sprint, in plain language, regardless of what the commit messages claimed? Which part of the codebase keeps churning? Which effort introduced the most rework? These are the questions engineering leads actually ask and rarely get straight answers to, because the straight answer is buried in diffs nobody has time to read. That is the direction WhyGraph is built to grow into. It is not a dashboard you can open today, and I am not going to pretend otherwise. But the foundation, a description of every change grounded in the code itself rather than in what someone typed in a hurry, is the hard part, and it is already there.

When to reach for it, and when not

WhyGraph earns its place on codebases with real history. If you have years of commits, pull requests, and closed issues, the reasons are all in there, and its job is to surface them at the right moment. It is especially useful on legacy code whose original authors have long since moved on, where the "why" is otherwise unrecoverable without genuine archaeology. And it pays off most when AI agents are doing real editing in your workflow, because that is exactly when unspoken context turns into silent regressions. Picture a migration that touches a payments module: before changing a single guard clause, the agent, or the engineer driving it, can see why each one is there. The clauses that look paranoid usually turn out not to be.

It is worth being just as clear about the other side. A brand-new repository with a handful of commits does not have much history to mine yet, so WhyGraph has less to tell you. It explains reasons that exist. It does not invent them where the record is thin. If your history is mostly squashed merges with no linked issues, it will be honest about how little it found rather than confidently making something up, which is the behavior you want even when it is not the behavior you were hoping for. And it raises the bar on AI edits rather than guaranteeing perfect ones. An agent with WhyGraph is a better-informed agent, not an infallible one. That is a meaningful difference, but it is a difference of degree, and I would rather say so plainly than oversell it.

Try it

WhyGraph needs nothing on the host but Docker. One line to install:

curl -fsSL https://raw.githubusercontent.com/mtrdesign/whygraph/main/scripts/install.sh | sh

Then, from the repository you want to understand:

whygraph init                 # bootstrap the WhyGraph DB + write config
whygraph scan                 # crawl history + refresh CodeGraph + LLM descriptions
whygraph init --agent claude  # wire the MCP server into your editor
whygraph-mcp                  # sanity-check the server (Ctrl-C to exit)

That is the whole setup. whygraph init prepares the database and config, whygraph scan reads your history and describes it, and whygraph init --agent claude wires the MCP server into your editor. Full documentation, including every other install path and every supported editor, lives in the WhyGraph documentation, and the source is available on GitHub.

None of this makes your AI agent smarter. It just means the next one that decides your weird retry loop is needless complexity will at least have to read why it is there first. Which, most days, is enough.