Smithers Review

Code review that turns a pull request into a readable walkthrough.

We built a GitHub-native review system that authenticates with OIDC, runs one agent per changed file, writes a story-form HTML review, and publishes an unlisted link for humans to inspect.

Open the sample walkthrough See how it works

What we built

A CodeRabbit-style review bot for Smithers, but with a stronger artifact: a single HTML walkthrough that explains the change in reading order.

1

Pull request review

When a PR is opened, updated, or requested by comment, the GitHub Action checks out the code and runs the review flow.

2

Parallel agents

Smithers splits the diff by file and gives each reviewable file to an agent. Findings are collected without failing the build.

3

Published walkthrough

A narrator turns the whole diff into chapters with embedded diffs, diagrams, summaries, and links back to the PR.

The simple version

The reviewer is a pipeline. GitHub triggers it, Smithers orchestrates it, agents inspect the change, and the service publishes the result.

PR
Pull request changes A contributor opens, updates, or comments on a PR.
GH
GitHub Action starts The workflow runs with read access and PR review permission.
ID
OIDC session The service verifies the repo identity without a stored secret.
AI
Review agents run Smithers fans out file reviews and narrates the change.
URL
Review is posted GitHub gets inline comments and an unlisted walkthrough link.

How it is wired

The system is split into a small GitHub Action, a local CLI runner, and a Cloudflare Worker service.

A

Action package

apps/review/action gates events, installs dependencies, checks out the PR, and launches the review CLI.

B

Review workflow

apps/review/src/workflow resolves the target, previews files, runs agents, and renders the HTML walkthrough.

C

Hosted service

apps/review/src/server mints sessions, proxies metered inference, stores walkthroughs, and exposes metrics.

D

GitHub posting

apps/review/src/github turns findings into a PR review body and inline comments with suggestions.

Inside GitHub Actions

  • Reads the event payload
  • Skips drafts and unauthorized comments
  • Fetches a GitHub OIDC token
  • Runs bun apps/review/src/cli/main.ts

Inside review.jjhub.tech

  • Verifies the OIDC token against GitHub JWKS
  • Checks repo registration and monthly quota
  • Issues a short-lived session token
  • Stores HTML walkthroughs in R2

Inside Smithers

  • Splits work into workflow tasks
  • Runs review agents in parallel
  • Combines findings into a final result
  • Builds a story from the full diff

Back in the PR

  • Posts a narrative review body
  • Adds inline comments where possible
  • Includes the hosted walkthrough URL
  • Leaves merge decisions to humans

The request lifecycle

Each lane owns one responsibility. This keeps credentials short-lived and keeps untrusted PR code away from long-lived secrets.

Developer
opens PR or comments @smithers review reads walkthrough
GitHub Action
gates event requests OIDC token checks out PR runs CLI
Review Service
verifies identity checks quota proxies inference stores HTML
Smithers
loads diff fans out agents narrates change posts findings

Why OIDC matters

The user does not paste a platform secret into their repo. GitHub proves which repository is running, and the service returns a short-lived session.

!

No pull_request_target. The workflow runs on pull_request because the agents inspect PR code. Running with elevated target-repo credentials would be the wrong trust boundary.

pull_request opens
  -> GitHub Action asks GitHub for OIDC token
  -> review service verifies token signature and claims
  -> service checks repo registration and quota
  -> service returns a 2-hour session token
  -> CLI uses that token for inference and publishing

What the output looks like

The artifact is intentionally plain: one static HTML file with prose, embedded diffs, diagrams, and every reviewed file in context.

1
Headline A short name for the change.
2
Synopsis What changed and why it matters.
3
Chapters Files grouped in logical reading order.
4
Diffs Every relevant hunk embedded inline.
5
Findings Inline PR comments when the agent finds something actionable.

Sample deployed walkthrough: https://review.jjhub.tech/w/wxkid6oa8vme

Add it to a repo

Users add one workflow. The service side decides whether the repo runs automatically or waits for the magic comment.

name: smithers review
on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
  issue_comment:
    types: [created]

permissions:
  id-token: write
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: smithersai/smithers/apps/review/action@main