SI Agent News
DevelopingClaudeOpenAIOpen modelsAgents

Gavel makes coding agents explain their own changes before you approve them

A free, open-source tool has Claude Code or Codex write a guided walkthrough of its own edits, so the human reviewer starts with context instead of a raw diff.

350+commits in about 3 weeks of building gavel

The short version

Why it matters

Coding agents can produce changes faster than a person can read them, so the human check is where quality gets lost. Gavel tries to cut the effort of that check so it doesn't get skipped when you're tired. Even if you never use it, the idea of making an agent argue its case is one you can borrow.

The review problem gavel targets

As photostructure.com described it, gavel grew out of a long project: adding sign-in and permission controls to the PhotoStructure photo software. The developer wrote the database layout and the onboarding flow himself. Claude and Codex, two AI coding agents, filled in much of the rest over several hundred sessions, and he reviewed every change before it was committed (saved to the project's history).

His routine was tedious. He staged the agent's edits in Git, read them in VS Code, and typed out the file path, line number and his feedback to send back to the agent. He says that friction matters, because a tired reviewer starts waving things through.

Borrowing a trick from interns

The fix came from an earlier job. There, he helped interns get their pull requests (proposed code changes) accepted by having them write a story around the change. Why was it needed? What other options were considered? Why was this one chosen? Where would you begin if explaining it to engineers who know the codebase but not your problem?

He realized an agent could write that story too. A short brief up front, plus comments attached along the diff, would let the reviewer spend their attention on judging the change rather than figuring out what it is.

He found existing agent apps lacking: their diff viewers don't thread comments. So he forked difit, an open-source GitHub-style diff viewer by yoshiko-pg, and added the agent connection and the guided flow. He asks users to consider sponsoring difit's author.

What a review looks like

You install gavel, add a small instruction file called a skill to your agent, and type /gavel in Claude Code or $gavel in Codex. The agent opens a review in your browser. A summary panel opens with the reason for the change and a proposed commit message to check against the code.

The agent splits larger work into parts by purpose and orders them for understanding. Preparatory cleanup can come first, and tests and documentation sit with the code they relate to. Each part gets its own tab, brief and verdict.

A "Start here" marker begins a guided tour, and each stop has a Next link. Explanations sit next to the code, and links jump to specific lines, files or other reviews. The tour only sets a reading order. The full diff stays open to you.

Questions, change requests and verdicts

Say you want proof that a 404 error is not retried in the example change. You leave a Change request on those lines. The agent writes the test and answers in that thread with a link, so you can check it before signing off. You can also post a Question or a plain Comment, and resolve a thread when it's settled.

Each part gets a verdict. Approve lets the agent commit once it has handled your comments and passed required checks. Reject halts it, and it asks what to do instead and whether to undo the work. You can change a verdict until the agent acts on it.

Phone access and how feedback reaches the agent

The same threads and verdict buttons work on a phone. You ask the agent for a link your phone can reach. The link includes an access token, and gavel needs it to load a review or accept comments and verdicts, so the project recommends HTTPS for remote use.

To pass your feedback back, gavel uses the Claude session socket or a Codex feature called codex queue, which notifies the agent session without it repeatedly checking for news. If a message doesn't arrive, a Copy resume prompt option lets you paste the context into the session by hand. You need to keep the chat open while you review.

Limits and what to keep in mind

Gavel is a young project built by one developer for his own workflow. The write-up says it took about 3 weeks and over 350 commits, and that he used gavel to review its own code. That is a good sign of real use, but it isn't independent testing.

There is also a structural caveat: the agent writing the explanation is the one defending its work. A persuasive tour could make a flawed change feel more reasonable. The tool keeps the whole diff visible and lets you interrogate each choice, but the discipline of actually reading the code stays with you.

What to watch

Try it

On a small, low-risk Git project with Node.js 22.20 or newer, run npm install -g @photostructure/gavel, add the skill for Claude Code or Codex, and type /gavel before your next commit.

Sources and links

Liked it? Say why

Add a line for other readers.

No account needed. We never show your email. Comments with links, ads or abuse are held and not shown. Your comment shows after a quick check.

Listen to the AI Wire headlines

Listen to the AI Wire

Listen to our daily AI shows every morning: on your commute, in the shower, wherever you are

Listen to the daily shows

First reported by photostructure.com · Read the original. Written by the SI Agent News Desk from the reporting above.Written with AI from the source above. Every number is checked against the source. Spot a mistake? Corrections.

More AI news