# DiffNotes

> Lets coding agents attach plain-language notes, screenshots and live demos to pull request diffs, shown via a browser extension on GitHub, GitLab and Bitbucket.

DiffNotes is an open-source (MIT) tool by Igor Kasyanchuk that lets a coding agent explain its own pull request. The agent uploads notes, screenshots and small demos to a DiffNotes server, and reviewers see them inside the diff on GitHub, GitLab or Bitbucket through a browser extension. Nothing is posted to the pull request itself. It can be used on the hosted server at diffnotes.dev or self-hosted with Docker.

## What It Is

DiffNotes is a pull request annotation tool built around coding agents such as Claude Code, Codex, Cursor and other Agent Skills tools, with an MCP endpoint as an alternative to the skill. The agent that wrote the code explains each changed file and the non-obvious lines, flags risky parts such as auth, money or migrations, and attaches supporting material. The notes are stored on a DiffNotes server rather than posted as bot comments, so there is no notification noise.

## How the Workflow Runs

A user signs in with GitHub, installs the browser extension and connects it, then runs one setup command for their agent. On a branch with an open pull request, the agent is asked to annotate it and uploads the notes. Reviewers opening the Files changed view see a summary box above the first file, a list of where to look hardest, and notes attached to the changed lines. Notes added or changed since a reviewer's last visit are tagged, and a dock and keyboard shortcuts help navigate them.

## Note Content and Repository Rules

Notes can include before/after screenshots with a drag handle, screen recordings, image galleries, previews of Markdown, CSV and text files, Mermaid flowcharts, and small HTML demos that run in a sandbox with no network access. A `.diffnotes.yml` file in the repository, read from the base branch, can set the language, require risk ratings or deploy cards, skip paths, and choose paths for screenshots. After new commits the agent can update notes and remove stale ones.

## Hosting and Teams

Accounts have owner, admin and member roles, with invitations by email, GitHub login or an expiring link. Files can be stored on disk or in S3-compatible storage. The project states that notes expire after a year by default, and a single extension can connect to several servers.

## Features
- Agent-written plain-language notes attached to changed lines
- Summary box and where-to-look-hardest risk list
- Before/after screenshots, screen recordings and image galleries
- Sandboxed live HTML demos
- Mermaid flowcharts rendered in the diff
- Previews of Markdown, CSV and text attachments
- Notes updated or removed after new commits
- What-changed-since-last-visit tags
- Repository rules via .diffnotes.yml
- Team accounts with owner, admin and member roles
- Self-hosting with Docker and S3-compatible storage
- MCP endpoint and Agent Skills support
- Nothing posted to the pull request

## Integrations
GitHub, GitLab, Bitbucket, Claude Code, Codex, Cursor, MCP, Chrome, Edge, Brave, Arc, Docker, Backblaze B2, Cloudflare R2, AWS S3, MinIO

## Platforms
WEB, BROWSER_EXTENSION, API, CLI

## Pricing
Open Source

## Version
1.8.1

## Links
- Website: https://diffnotes.dev
- Documentation: https://diffnotes.dev/docs
- Repository: https://github.com/igorkasyanchuk/diffnotes
- EveryDev.ai: https://www.everydev.ai/tools/diffnotes