TL;DRgavel is a local, GitHub-style review tool for your coding agent’s changes. Its skill tells your agent to break large changes into smaller pieces you can understand and judge one at a time, with a guided walkthrough of each diff. Start with an introductory comment, then follow links from one explanation to the next and jump to the code each one describes.Your agent does this preparation to get you up to speed, so you can spend your attention judging whether the change should ship.
Ask questions beside the code and work through revisions with the agent that wrote it. It replies in the threads and updates the diff in the same review. You give each part a verdict.There’s always more than one way to do itCodebases accumulate technical debt: inconsistencies in architecture and implementation, footguns, and unnecessary complexity. Every change can add to that debt or reduce it.The hard questions are what to change and how to make it fit the codebase.
Several implementations may work; Alice’s elegant solution may be indecipherable to Jane. Before I can judge a change, I need to understand the choices behind it.Reviews eat up your attentionMy brain only has so many thinks it can think in a day.I spent the past year reviewing my coding agent’s changes in my IDE. When I hit a “WTF?” change, I had to copy the code and context back into the agent’s chat.
After a few rounds of hunting through files and reconstructing intent, brain fade set in. The urge to say “fuck it, ship it” and move on was strong.I want the agent to explain its changes in pieces I can wrap my head around, while I still have the attention to question its choices.A diff needs a briefYour agent should do more of the work required to make its changes reviewable.
If I’m the judge, the agent should come prepared like a good attorney. Explain why the change is needed and why this approach fits the codebase. Show the evidence and point out the risks. For tricky code, I want expert-witness commentary on why it works and what could go wrong.I haven’t found another tool that helps an agent prepare that kind of review. I decided to build it myself fork difit, an excellent local diff viewer, and work with my agents to build gavel.gavel pairs a local diff viewer with an agent skill.
The skill tells your agent to explain its choices and guide you through the code before asking for approval. The viewer keeps those explanations and your questions beside the diff. I want to get through that review with a minimum of whiskey and friction.A review in gavelReview one piece at a timeThe skill tells your agent to split larger changes by purpose and put the pieces in the order you need to understand them.
A refactor can get its own review before the behavior change that builds on it. Tests and documentation stay with the code they explain. Each part gets a tab with its own explanation and verdict, so you have less to hold in your head at once.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.Read the brief before you ruleThe Change summary panel shows the agent’s explanation and proposed commit message at the top of the diff.
To change either one, ask the agent in a comment; it replies in the thread and proposes the new wording.Change summary: why the agent made the change, where its tour starts, and the commit message it proposesFollow the grand tourBefore asking you to review, the agent leaves comments explaining where to start, how the files fit together, and which choices deserve a closer look.For longer reviews, the skill tells the agent to link those comments into a tour.
A Start here link in Why this change takes you to the first stop. From there, follow links to the next explanation, a file, or specific lines of code. A tour can also cross into another proposed commit’s review.For example, the agent can take you from a new option to the code that handles it, then to the test that checks its behavior. Stop at any comment to question the agent, or take a detour into the code.
Your browser’s Back button returns you to the tour.A stop on the agent’s tour, with a link to the next oneQuestion the agentGitHub got the discussion format right: keep each conversation beside the change it concerns. On the lines you’re reading, choose Comment, Change request, or Question to tell the agent whether to take note, revise the code, or explain something.The agent answers in the same thread and can bring a revised diff back into the review.
You can write a follow-up, or resolve the thread when it needs nothing more.Use Conversation for questions about the whole change. It gathers those discussions alongside the inline threads.A change request the agent answered by adding the test to the reviewGive each part a verdictChoose 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.You can leave change requests and discuss revisions before choosing a verdict.
You can also change or clear your verdict until the agent acts on it.You can approve some parts while asking for revisions to others. Each tab keeps its own verdict; parts that belong to one commit must all be approved before the agent commits them.One tab per proposed commit, each with its own message and verdictGet startedgavel needs Node.js 22.14 or newer and a Git repository.
Install it with:npm install -g @photostructure/gavel Install the agent skill:npx skills add photostructure/gavel For Codex, follow the Codex setup guide to install its version of the skill.Then ask your agent:Open your changes in gavel for my review.To make review part of your usual workflow, add this to your AGENTS.md or CLAUDE.md:Request my review through gavel after you change code.See the README for command-line options.How the agent gets your feedbackgavel works with the agent session that opened the review.
Claude Code and Codex receive that feedback differently:Claude Code: gavel sends your verdicts and comments to the session that opened the review, which starts a turn even when idle. The agent can reply while you keep reviewing.Codex: gavel can queue your feedback for the chat that opened the review. Queued for Codex means the notification is saved; it doesn’t guarantee the agent has resumed.
If gavel can’t queue your verdict, the notice after it offers Copy resume prompt; paste the prompt into that chat. If the chat stays idle anyway, click the agent icon in the header and choose Copy resume prompt.No billable hours for waitingThe agent ends its turn while you review. The skills forbid polling for feedback, so it doesn’t spend model turns repeatedly checking whether you’re finished.
See waiting for review for handoff requirements and idle behavior.Hold court from your phoneYou can read the diff and reply to the agent from a phone. The threads and verdict menu fit the smaller screen.gavel has no login of its own. Before accessing it from another device, put it behind an authenticated HTTPS proxy or tunnel. See HTTPS and remote browsers for setup instructions.A question and the agent’s answer, on a phoneBuilt on difitgavel started as PhotoStructure’s fork of difit, yoshiko-pg’s GitHub-style diff viewer.
If gavel is useful to you, please consider sponsoring yoshiko-pg.Coding
