#
gavel is a local Git diff viewer for reviewing changes with the coding agent that wrote them. Its skill tells the agent to prepare a brief, explain its choices beside the code, and guide you through the diff.
Large changes are split into focused reviews, so you have less context to hold in your head at once. Ask questions in threads, request revisions, and give each part a verdict.
#
As a background task, I’ve been working for … longer than I’d like to admit on the task of adding authentication and authorization to PhotoStructure.
The fourth (!!) dev spike was the charm—the first three attempts left me with a pretty solid set of specifications to guide the implementation.
I wrote the db schema and the onboarding flow. Claude and Codex helped flesh out the implementation over several hundred sessions, coordinated with technical project plans.
I reviewed every change before committing it. And it’s been a slog. It’s a given that authentication and authorization are going to be hard. But I felt like my reviewing approach kinda sucked had a lot of opportunity for improvement.
For the past year-ish, my workflow with coding agents was to:
- have an agent cook
- have it pass second-opinion
- stage the diffs in git, and then
- review those diffs in VS Code, and
- for any issues or nits that I found, manually relay the relative file path and line number along with my guidance to the authoring session,
- repeat until the diffs are commit-worthy.
It’s a bit of a PITA. My brain only has so many thinks it can think in a day. Any friction to giving the robot feedback, especially as your brain fades, can let “fuck it, ship it” creep in.
I was explaining this to my wife during a walk, and realized that there was a better way.
At a prior job at a Big Company, I helped interns get their PRs approved and merged by having them write a narrative around their diffs.
- Why were they making this change?
- What alternative approaches did they consider?
- Why did they pick this approach?
- If you were presenting this PR to a review board of engineers that knew the codebase, but didn’t know the background of your problem, where would you start?
- What other critical parts of the diff are odd, confusing, or warrant attention?
This approach helps walk the reviewer through the PR, and is way better than the asciibetical sort order of staged diffs and a proposed git commit message that I’d been slogging through.
The reviewer spends their limited cognitive mojo on judging the PR, not on basic orientation and background arcana.
I realized I could ask my agent to do this.
If the agent could write a “brief” for every review–just a sentence or three–and then add linked comments through the diffs to walk me through the changes, each review would be much simpler to digest and wrap my brain around.
The edit to the AGENTS.md would be super simple! Barely an inconvenience!
But, ugh, agents still work via a glorified chat interface. The Codex and Claude desktop apps, for example, each have a diff tool, but neither threads your comments. Juggling multiple issues simultaneously in one review is work. I’ve also seen the Codex diff viewer get confused and show irrelevant diffs from other worktrees. None of this is visible on their mobile apps.
I looked for an open source tool that provided a UX for a “present your diffs” style workflow. The closest I found was difit, yoshiko-pg’s GitHub-style diff viewer, so I forked it to add the agent integration and guided review workflow I needed.
If gavel is useful to you, please consider sponsoring yoshiko-pg.
gavel gavels gavel (and PhotoStructure!)
3 weeks and 350+ commits later, @photostructure/gavel now delivers the “grand circle tour” guided review that I had envisioned. Along the way, I used gavel to review every line of its own changes.
#
The screenshots below follow a small retry helper change: wait longer between attempts and stop retrying client errors such as HTTP 404.
The agent groups changes by purpose and puts them in the order you need to understand them. A refactor can come before the behavior change that depends on it. Tests and documentation stay with the code they explain. Each part gets a tab, a brief, and a verdict.
When the parts build and pass tests independently, the agent proposes separate commits. When they need to land together, you can still review them separately: the agent waits for every part’s approval before making one commit.
The Change summary panel starts with why the agent made the change. In this example, the brief explains that retries will wait longer and errors that cannot succeed will fail at once. Beside it is the proposed commit message, ready for you to check against the code.
Follow Start here in Why this change. The first stop explains the new wait between retries; its Next link takes you to where the status code comes from. The explanations sit beside the code they discuss, and links can take you to specific lines, files, or another review.
The tour gives you a reading order. The whole diff is still there to inspect, and you can ask the agent why it made any change. Your browser’s Back button returns you after a detour. Press ? to see the keyboard shortcuts.
At the status-code check, suppose you want a test proving that a 404 isn’t retried. Leave a Change request on those lines. The agent adds the test and replies in the same thread with a link, so you can inspect it before approving.
Choose Question when you want an explanation, or Comment to leave a note. Each discussion stays beside the change it concerns, so you can follow up without copying paths and line numbers back into chat. You can resolve a thread when it needs nothing more.
Use Conversation for questions about the whole review and to see its inline threads in one place. Choose Unread to catch up on agent replies across reviews, or All reviews to browse their conversations.
Once you’ve read the code and worked through your questions, choose how the agent should proceed:
- Approve gives it permission to commit once it has addressed your comments and passed the required checks and reviews.
- Reject stops the agent, which asks you what to do instead and whether to revert.
Each tab keeps its own verdict. In this example, the retry change is approved while the README review remains open. You can change or clear a verdict until the agent acts on it.
The same threads and verdict controls work on a phone, so you can read the agent’s explanations and reply away from your desk.
Ask your agent for a review link your phone can reach. The full link includes an access token; gavel requires that token to load the review or send comments and verdicts. Use HTTPS for remote access to protect the token and review traffic.
#
Use Node.js 22.20 or newer for the commands below, and run them from the Git repository you want to review. Install gavel:
npm install -g @photostructure/gavel
Then install the skill for your agent.
Claude Code: run this in your terminal:
npx skills add https://github.com/photostructure/gavel/tree/main/skills/gavel --agent claude-code --global --copy
Codex: paste this into Codex, using its built-in skill installer:
Use $skill-installer to install the Codex version of gavel from https://github.com/photostructure/gavel/tree/main/.codex/skills/gavel
For automatic feedback, including in Codex Desktop, gavel needs a Codex CLI that supports codex queue on its PATH. Keep the chat open while you review.
To start a review, type /gavel in Claude Code or $gavel in Codex.
To make review part of your usual workflow, add this to your AGENTS.md or CLAUDE.md:
Before committing your changes, request my review through the gavel skill.
gavel uses the Claude session socket or codex queue to notify the session that opened the review without spending model turns polling while you read.
The agent icon shows delivery status. If feedback can’t reach the agent, or the Codex chat stays idle, choose Copy resume prompt from the verdict notice or the agent icon and paste it into the session that opened the review.