I made my coding agent explain its own pull requests
The problem: the agent knows why, the reviewer doesn't More and more of the pull requests I review were written by a coding agent. The code is usually fine. Reviewing it is not: I open Files changed , see 400 lines across 12 files, and start reverse-engineering the reasons behind each block. The funny part is that the agent knew those reasons. It had just made every decision. By the time a human…
A coding agent writing pull requests is becoming more common, but reviewing them can be challenging. The agent writes code flawlessly, but the reviewer struggles to understand the reasoning behind each line of code. The agent has already made all the decisions, so by the time a human opens the diff, the context is lost. To address this issue, I created a tool called DiffNotes.
A note in DiffNotes is a concise, plain-language explanation attached to a changed block of code. It is displayed alongside the diff, providing a summary of the PR, deploy steps, and areas to focus on. Notes can include screenshots, Markdown reports, CSV files, and small HTML demos that run in a sandbox. Setting up DiffNotes is quick and easy:
1. A server is required. You can use the free hosted version at diffnotes.dev or run your own using Docker. The setup requires a GitHub account and an email address.
2. Install the agent skill on each developer's machine. This can be done with a single command provided by the welcome page.
3. Install the extension for reviewers in the Chrome Web Store. Upon installation, you'll need to sign in and enter your server details.
Once the setup is complete, the reviewer can annotate a pull request with DiffNotes. The agent reads the diff and uploads a summary, deploy card, risk list, and one note per changed block, explaining why the changes were made. The extension displays these notes next to the relevant lines in the diff, making it easier for the reviewer to understand the reasoning behind each change.
DiffNotes does not post any information to GitHub, keeping the PR conversation human-focused. The notes live on your server, ensuring privacy, and they expire over time. The tool is free, open-source, and small in size, making it easy to integrate into any development workflow. If your team reviews AI-written code, I encourage you to try DiffNotes and provide feedback on how it can improve your review process.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
