跳到正文
AI NEWS JOURNAL
Hacker News Show HNAI NEWS / JOURNAL

Show HN: gavel: guided code review with your coding agent

Howdy!I've been working on an open-source tool that helps lighten the burden of reviewing what your coding agents write. You still see all the lines of code, but the agents write a "tour guide" that links you through the local PR, and as you have questions or comments, you chat with your agent in the context of the code, in a threaded conversation.I called it "gavel" (you make your agents build a case that you judge). Hope you find it as useful as I do!https://github.com/photostructure/gavel Comments URL: https://news.ycombinator.com/item?id=50512685 Points: 1 # Comments: 0

翻译服务暂未运行,当前显示原文。

🧑‍⚖️ TL;DR Your agent makes the case for its code. You give the verdict. Review local Git changes in your browser with Claude Code or Codex. The gavel skill tells your 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. gavel is free and MIT-licensed. Development is sponsored by PhotoStructure. Requires Node.js 22.20+: npm install -g @photostructure/gavel Set up your agent to enable guided reviews. ❓ Why gavel, and why now 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. ⛏️ How I had Clauded 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. 🎤 Present your diffs 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. 🤖 OMG robots could do this too 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. The Codex iOS app is supposed to show diffs, but that hasn’t worked for me, and the Claude iOS app doesn’t even have diffs afaict. 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. Support difit: 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. 💼 A review in gavel The screenshots below follow a small retry helper change: wait longer between attempts and stop retrying client errors such as HTTP 404. 🧩 Review one piece at a time 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. 📋 Read the brief before you rule 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. Change summary: why the agent made the change, where its tour starts, and the commit message it proposes 🧭 Follow the grand tour 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. A stop on the agent’s tour, with a link to the next one 🗣️ Question the agent At the next stop, 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. A change request the agent answered by adding the test to the review 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. ⚖️ Give each part a verdict 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. Each review has its own verdict: retry-backoff is approved; readme-retries is still open 📱 Review from your phone 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. See remote browser setup. A question and the agent’s answer, on a phone 🚀 Get started 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. 🤖 How the agent gets your feedback 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.

资料来源

阅读原文 ↗

相关主题

← 继续阅读全部动态