annai

Annai (案内) — Claude Code Code Review Surface

Turn a code review into a guided browser surface. Two agent skills — review-pr (review a GitHub pull request) and review-local (review code an LLM agent just produced locally) — generate a structured, ordered view of the change: base context first, then entry points, then supporting code, with typed side notes, inline suggestions, and mermaid diagrams. A local server renders it. In PR mode the reviewer's decision pushes to GitHub via GraphQL; in local-agent mode it lands as result.json for the agent to read back.

Why

Reviewing a PR you don't already have the context for is mostly assembly work: jumping between Notion, Slack threads, design docs, and the diff just to build a mental model before you can judge anything. Annai moves that assembly into an agent step and hands the reviewer a surface that explains the why alongside the what — in the order that makes sense.

Read the long form in docs/code-review-surface.md; the runtime design lives in docs/annai-architecture.md.

Features

• Ordered surface. Base context → entry points → supporting code, not alphabetical file list. Group-level intros explain why a set of diffs belongs together.
• Typed side notes on individual diffs — note, question, pattern, surface-check, discrepancy — rendered in a column alongside the code so the reviewer reads the why next to the what.
• Agent suggestions inline. The agent can attach suggestion blocks with an alternative snippet; the reviewer accepts as a draft comment or dismisses with one click.
• Mermaid diagrams at the PR level or per-group, with light- and dark-theme palettes that follow the page toggle.
• Markdown everywhere. Tldr, group intros, annotations, suggestions, drafts, and review prompts all render markdown (code, lists, links, bold).
• Drafting: line, multi-line range, whole-file (composer is attached to the file header so it expands inline under the diff bar), and the overall PR body. Every composer accepts Ctrl/Cmd+Enter to save.
• Decision picker: in PR mode, Approve, Comment, or Dismiss session. In local-agent mode, Finish review (no Approve — there's nothing to approve against) or Dismiss session. Submitting opens a confirmation modal that previews the queued comments grouped by file and lets you author the overall body right there.
• Single-shot GitHub submission (PR mode) via gh api graphql: one addPullRequestReview (with line/range threads), one addPullRequestReviewThread per file-level draft (subjectType: FILE), one submitPullRequestReview to finalise. All comments land in one review event — the reviewer never sees them arrive one at a time.
• Local-agent terminus. In local-agent mode there's no GitHub call; the daemon writes result.json and annai.sh result --session <id> dumps it for the agent to read back as feedback.
• Light / dark theme with a one-click toggle in the top nav. Mermaid, the diff viewer, and every annotation respect it.
• Surface authoring CLI the agent drives instead of plain-editing surface.json: scaffold parses a GitHub PR diff into a typed skeleton, scaffold-local does the same from a local git diff the agent ran itself, and *-add / *-update / *-drop / set-* mutate the surface atomically with zod validation on every write.
• Client-side error capture. window.onerror, unhandled rejections, and React error boundaries all POST to the daemon and surface in annai.sh status and on the watch stream.

Install

From the asermax-plugins marketplace:

/plugin marketplace add asermax/claude-plugins
/plugin install annai@asermax-plugins

Or point Claude Code directly at this repo.

Usage

From any Claude Code session in the repo you want to review:

/annai:review-pr <PR url or number>      # review a GitHub PR
/annai:review-local                      # review the current local change

Either skill will: