{"slug": "show-hn-gavel-an-open-source-local-code-review-tool", "title": "Show HN: Gavel, an open source local code review tool", "summary": "A developer released Gavel, an open source local Git diff viewer that lets coding agents present their changes for human review, built over 3 weeks and 350+ commits as a fork of yoshiko-pg's difit diff viewer. Gavel's skill instructs the agent to write a short brief, explain its choices beside the code, split large changes into focused reviews, and support threaded questions and per-part verdicts, addressing the author's workflow of relaying file paths and line numbers manually between VS Code and Claude or Codex sessions while adding authentication and authorization to PhotoStructure. The tool targets the friction that the author says lets \"fuck it, ship it\" creep in as review fatigue sets in.", "body_md": "# Your agent makes the case for its code. You give the verdict.\n\n## \n\n`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.\n\nLarge 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.\n\n## \n\nAs 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.\n\nThe fourth (!!) dev spike was the charm—the first three attempts left me with a pretty solid set of specifications to guide the implementation.\n\nI 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](https://photostructure.com/coding/claude-code-tpp/).\n\nI 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.\n\n### \n\nFor the past year-ish, my workflow with coding agents was to:\n\n1. have an agent cook\n2. have it pass [second-opinion](https://photostructure.com/coding/claude-code-review/#when-one-reviewer-isnt-enough-ask-both-models)\n3. stage the diffs in git, and then\n4. review those diffs in VS Code, and\n5. 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,\n6. repeat until the diffs are commit-worthy.\n\nIt’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.\n\nI was explaining this to my wife during a walk, and realized that there was a better way.\n\n### \n\nAt 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**.\n\n- Why were they making this change?\n- What alternative approaches did they consider?\n- Why did they pick this approach?\n- 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?\n- What other critical parts of the diff are odd, confusing, or warrant attention?\n\nThis 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.\n\nThe reviewer spends their limited cognitive mojo on judging the PR, not on basic orientation and background arcana.\n\n### \n\nI realized **I could ask my agent to do this**.\n\nIf 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.\n\nThe edit to the `AGENTS.md` would be super simple! Barely an inconvenience!\n\nBut, 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.\n\nI looked for an open source tool that provided a UX for a “present your diffs” style workflow. The closest I found was [difit](https://github.com/yoshiko-pg/difit), yoshiko-pg’s GitHub-style diff viewer, so I forked it to add the agent integration and guided review workflow I needed.\n\nIf gavel is useful to you, please consider [sponsoring yoshiko-pg](https://github.com/sponsors/yoshiko-pg).\n\n### `gavel` gavels `gavel` (and PhotoStructure!)\n\n3 weeks and 350+ commits later, [@photostructure/gavel](https://github.com/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.\n\n## \n\nThe screenshots below follow a small retry helper change: wait longer between attempts and stop retrying client errors such as HTTP 404.\n\n### \n\nThe 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.\n\nWhen 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.\n\n### \n\nThe **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.\n\n### \n\nFollow **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.\n\nThe 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.\n\n### \n\nAt 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.\n\nChoose **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.\n\nUse **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.\n\n### \n\nOnce you’ve read the code and worked through your questions, choose how the agent should proceed:\n\n- **Approve** gives it permission to commit once it has addressed your comments and passed the required checks and reviews.\n- **Reject** stops the agent, which asks you what to do instead and whether to revert.\n\nEach 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.\n\n### \n\nThe same threads and verdict controls work on a phone, so you can read the agent’s explanations and reply away from your desk.\n\nAsk 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.\n\n## \n\nUse Node.js 22.20 or newer for the commands below, and run them from the Git repository you want to review. Install gavel:\n\n```\nnpm install -g @photostructure/gavel\n```\n\nThen install the skill for your agent.\n\n**Claude Code:** run this in your terminal:\n\n```\nnpx skills add https://github.com/photostructure/gavel/tree/main/skills/gavel --agent claude-code --global --copy\n```\n\n**Codex:** paste this into Codex, using its built-in [skill installer](https://learn.chatgpt.com/docs/build-skills#install-curated-skills-for-local-use):\n\nUse $skill-installer to install the Codex version of gavel from [https://github.com/photostructure/gavel/tree/main/.codex/skills/gavel](https://github.com/photostructure/gavel/tree/main/.codex/skills/gavel)\n\nFor 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.\n\nTo start a review, type `/gavel` in Claude Code or `$gavel` in Codex.\n\nTo make review part of your usual workflow, add this to your `AGENTS.md` or `CLAUDE.md`:\n\nBefore committing your changes, request my review through the gavel skill.\n\n### \n\n`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.\n\nThe 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.", "url": "https://wpnews.pro/news/show-hn-gavel-an-open-source-local-code-review-tool", "canonical_source": "https://photostructure.com/coding/gavel/", "published_at": "2026-11-16 00:52:02+00:00", "updated_at": "2026-11-16 01:22:38.519632+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-products"], "entities": ["Gavel", "PhotoStructure", "Claude", "Codex", "difit", "yoshiko-pg"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-gavel-an-open-source-local-code-review-tool", "markdown": "https://wpnews.pro/news/show-hn-gavel-an-open-source-local-code-review-tool.md", "text": "https://wpnews.pro/news/show-hn-gavel-an-open-source-local-code-review-tool.txt", "jsonld": "https://wpnews.pro/news/show-hn-gavel-an-open-source-local-code-review-tool.jsonld"}}