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 fu
nny part is that the agent knew those reasons. It had just made every decision. By the time a human opens the diff, that context is gone. I tried asking the agent to write PR comments.
That works, but every comment pings the whole team, the agent's text mixes with the human discussion, and it all stays in the PR forever. So I built DiffNotes. A note is a short, plain-language "why" attached to a changed block: On top of the diff, a summary box shows what the PR does, the deploy steps, and where to look hardest: Notes can carry screenshots (before/after, mobile/desktop), Markdown reports, CSVs and small HTML demos that run in a sandbox right under the note. 1.
A server. Use the free hosted one at diffnotes.dev (sign in with GitHub), or run your own: docker run -d -p 3000:3000 -v diffnotes:/data \ -e ADMIN_EMAIL=you@company.com -e PUBLIC_URL=https://reviews.example.com \ ghcr.io/igorkasyanchuk/diffnotes 2. The skill, on each developer machine. The welcome page gives you this command with your token already filled in: curl -fsSL https://diffnotes.dev/install.sh | DIFFNOTES_SETUP_TOKEN=dn_… sh It installs an Agent Skill that Claude Code, Codex, Cursor and other skills-aware agents pick up.
If your agent speaks MCP instead: claude mcp add --transport http diffnotes https://diffnotes.dev/mcp \ --header "Authorization: Bearer $DIFFNOTES_TOKEN" 3. The extension for reviewers: Chrome Web Store. It opens a tab on install: enter your server, sign in, done. When the PR is ready: annotate this PR with diffnotes The agent reads its own diff and uploads: a summary of the PR a deploy card (migrations, flags, rollback) a risk list: which spots deserve the closest look one note per changed block, explaining why, not restating what screenshots or a small demo when the UI changed You can add per-repository rules in a .diffnotes.yml on the base branch, for example "every migration needs a deploy note". The agent reads them before writing. Open Files changed. The extension draws the notes next to the lines. Scroll away and a small dock keeps the note count and a switch to hide everything.
Images open in a gallery; a demo expands to phone, tablet or desktop width. Try it without installing anything: diffnotes.dev/demo. No noise. The PR conversation stays human.
Privacy. Notes live on your server. Only members of the account that owns the repository can read them. They expire.
Explanations of a diff are useful during review, not forever. DiffNotes is MIT and small on purpose: one container, SQLite, two runtime dependencies. If your team reviews AI-written code, I'd love to hear what would make those reviews faster. ⭐ github.com/igorkasyanchuk/diffnotes
Key Takeaways #
- •It had just made every decision.
- •This story was reported by Dev.to , covering developments in thedev space.
- •AI advancements continue to reshape industries — read the full article on Dev.to for complete coverage.
📖 Continue reading the full article: