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 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.
What a good note looks like
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.
Setup in about 5 minutes
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.
Ask the agent
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.
What reviewers see
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.
Why nothing is posted to GitHub
- 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.
What's next
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.
Top comments (0)