I made my coding agent explain its own pull requests
---
title: I made my coding agent explain its own pull requests
published: true
tags: ai, github, codereview, opensource
cover_image: dev-to-uploads.s3.us-east-2.amazonaws.com
---
<!-- Day 6. Add one paragraph of your own in section 1 (a real PR from your team). Publish on dev.to, then cross-post to Hashnode and Medium with the dev.to URL as canonical. -->
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:
!Image description
On top of the diff, a summary box shows what the PR does, the deploy steps, and where to look hardest:
!Image description
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.
!Image description
Try it without installing anything: diffnotes.dev.
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.
⭐ igorkasyanchuk/diffnotes
Mentions
DiffNotes' README describes agent explanations displayed inside diffs. A rationale isn't a passing test. Proposed review exercise: pair one explanation with a failing case it should prevent. What evidence is missing? igorkasyanchuk/diffnotes
I made my coding agent explain its own pull requests --- title: I made my coding agent explain its own pull requests published: true tags: ai, github, codereview, opensource cover_image: dev-to-uploads.s3.us-east-2.amazonaws.com --- <!-- Day 6. Add one paragraph of your own in section 1 (a real PR from your team). Publish on dev.to, then cross-post to Hashnode and Medium with the dev.to URL as canonical. --> 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: !Image description On top of the diff, a summary box shows what the PR does, the deploy steps, and where to look hardest: !Image description 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. !Image description Try it without installing anything: diffnotes.dev. 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. ⭐ igorkasyanchuk/diffnotes
コードの変更理由を差分の横で読めるDiffNotesの使い方が公開されています。 AIが書いた説明は専用サーバーに保存し、ブラウザ拡張でPRの変更箇所に重ねて表示する仕組みです。 PRへコメントを投稿しないため、通常の会話と分けて確認できます。 igorkasyanchuk/diffnotes
DiffNotes 开源了 让 coding agent 给 PR 写「为什么改」 笔记贴在 diff 行旁 不往 GitHub 刷 bot 评论 还能自托管 你会先让它标 UI 还是标逻辑 igorkasyanchuk/diffnotes t.co
DiffNotes: Lets your coding agent explain its PRs inline