agent-code-review

PR review queue and scheduler for AI agents

Language
Go
Version
0.31.1
License
PolyForm Perimeter 1.0.0
Category
CLI Tool

A review daemon that finds candidate pull requests across your repos with the GitHub CLI, keeps a DuckDB-backed queue that survives restarts, and reviews each one by handing an assembled prompt to a pluggable engine — Codex or Claude Code. Eligibility holds keep a tight cadence cheap: only genuinely actionable work spends tokens. Ships a dashboard you can expose over Tailscale.

Features

01

Deterministic discovery — candidate PRs found via gh on their own cadence, never involving the LLM; approved PRs are skipped

02

Eligibility holds — a quiet period stops reviews mid-rebase, a re-review cooldown gives the author room to respond to the last one

03

Durable DuckDB queue — candidates, positions and review history survive restarts, which is what powers Refreshed detection

04

Pluggable engine — codex or claude, same verdict contract and same review log, so switching is a one-key config change

05

Live review logs — the engine tees into the workspace, so an in-flight review streams via queue log -f or the dashboard

06

Usage floors — the loop pauses when the engine's rate-limit window drops below a threshold, and resumes when it refills

07

Every engine metered side by side — see whether the one you are not using has more headroom before switching

08

Per-review spend recorded — token counts and API-rate cost, so a budget comes from your own data rather than a guess

09

Author groups as policy — ignore, comment or approve, per repo, each carrying its own engine and extra instruction

10

Serve with a dashboard — always-on daemon, optionally on your tailnet; most config reloads live within ~30s

11

Everything is config — repos, groups, thresholds, cadence, prompts and rules; no handles or repos hardcoded

12

doctor checks every runtime assumption at once, and serve runs the same checks at boot

Install

Homebrew

>_
$ brew install shhac/tap/agent-code-review

AI Agent Skill

>_
$ npx skills add shhac/agent-skills --skill agent-code-review --global

GitHub Release (macOS)

>_
$ curl -L https://github.com/shhac/agent-code-review/releases/latest/download/agent-code-review-darwin-arm64.tar.gz | tar xz

Go Install

>_
$ go install github.com/shhac/agent-code-review/cmd/agent-code-review@latest

Build from Source

>_
$ git clone https://github.com/shhac/agent-code-review.git && cd agent-code-review && make build

Getting Started

agent-code-review assumes only gh (authenticated), the duckdb CLI, and whichever engine you select — codex or claude, already authenticated. It never handles engine credentials. Run doctor to check all of that at once before your first cycle.

01 · Write the starter config

>_
$ agent-code-review config init

Repos, author groups, thresholds, cadence, prompts and rules all live in config.json.

02 · Add repos and roster the authors

>_
$ agent-code-review repos add your-org/your-repo

Then place people in groups with authors set. A group is a complete review policy: ignore, comment or approve.

03 · Set your prompts and dials

>_
$ agent-code-review config set candidates.rereview_cooldown 2h

Every command group has a usage subcommand with full docs and examples — repos usage, authors usage, prompts usage, config usage, queue usage.

04 · Kick a single cycle, then run the daemon

>_
$ agent-code-review serve --http :8330 --tailscale serve

Try agent-code-review run --once first. serve adds the dashboard and can expose it on your tailnet.

Usage

>_ Check every runtime assumption at once
$ agent-code-review doctor
>_ See the queue, holds and countdowns
$ agent-code-review queue ls
>_ Jump a PR to the front, clearing its hold
$ agent-code-review queue promote your-org/your-repo 1234
>_ Follow an in-flight review
$ agent-code-review queue log your-org/your-repo 1234 -f
>_ Put an author in a group for one repo
$ agent-code-review authors set your-org/your-repo some-handle approver
>_ Preview the prompt an author's PR would get
$ agent-code-review prompts preview --author some-handle
>_ Run one cycle and stop
$ agent-code-review run --once