claude-doc-review

Review Claude's design docs and plans like a pull request, without leaving the terminal.

When Claude writes a spec or a plan and says "please review it", you usually scroll the file, then type a long reply that quotes the parts you mean. claude-doc-review opens the document in a pane beside the conversation instead. You step through it block by block, pin comments on single paragraphs, bullets or table rows, and ask side questions that never enter the main conversation. When you're done, every comment goes back to Claude as one review.

_{Recorded with asciinema in a real terminal, reviewing this repo's own DESIGN.md. To replay it at full fidelity, run asciinema play docs/demo.cast.}

Why

• One review, one revision. All comments go back as a single prompt, each one anchored by heading path and quote. Claude revises the document once and keeps it coherent, instead of patching it piece by piece.
• Side questions stay on the side. "What does this paragraph mean?" doesn't belong in the main transcript. Asks are answered by a fork of the session, which reuses the cached prefix, so they're cheap and leave no trace in the conversation.
• Comments land exactly where you mean. Every heading, paragraph, list item, table and code fence is its own stop, and comments follow their passage when Claude edits the file.

Quick start

git clone https://github.com/revelationnow/claude-doc-review
claude --plugin-dir ./claude-doc-review/doc-review

Then, inside Claude Code:

/doc-review docs/superpowers/specs/2026-10-04-widgets-design.md

You can also skip the command. When a plugin such as superpowers writes a spec or plan and asks for a review, the pane opens by itself.

To load it in every session, add the absolute path of doc-review/ to CLAUDE_CODE_PLUGIN_DIRS in the env block of ~/.claude/settings.json.

What it does

Keys

Hotkeys work while the pane has the keyboard. It opens focused from /doc-review; otherwise click it or press ctrl+x tab.

Mouse

The mouse works wherever the surface reports it: fullscreen terminal, the desktop app and VS Code.

• Click a block's marker (·) to select it. Click the current marker (▶) to comment.
• Hover a block to show comment · ask · explain in the gap under it. Showing the row doesn't shift the layout.
• Every key has a button, including the toolbar, the answer actions, the ✕ on a comment, and the approve dialog.
• The wheel scrolls the pane. Documents with more than 200 blocks are drawn as a window around the current block, and the wheel moves the window at its edges.
• Wide tables and code have a bar under them: ‹ ───━━━━━─── › 41–88/102. Click the track to jump there, or click ‹ and › to step a screen at a time.

Configuration

Set these in /config or under pluginConfigs.doc-review in settings.

With auto, a pane that opens without a user action needs a terminal at least 144 columns wide (110 once you've opened it yourself). On a narrower terminal you get a toast pointing at /doc-review, which opens the pane at any width.

Where it runs

The desktop app and VS Code start sessions themselves, so --plugin-dir isn't available there. Load the mod in one of two ways:

• Put its path in CLAUDE_CODE_PLUGIN_DIRS in ~/.claude/settings.json. Add "CLAUDE_CODE_PLUGIN_DIR_WATCH": "1" if you want edits to hot-reload.
• Add this repo as a folder marketplace (claude plugin marketplace add <folder>), install the plugin from it, and run /reload-plugins after each edit.

Developing

claude plugin validate doc-review   # what the engine will load and refuse
claude plugin test doc-review       # 38 tests, no terminal needed
npx -p typescript@5 tsc -p doc-review

Type-checking needs the API declarations that the engine writes under doc-review/.claude-plugin/types/ the first time the mod loads in a session. The tests mount every view on the terminal, desktop and VS Code surfaces.

doc-review/
  .claude-plugin/plugin.json   manifest, userConfig, types contract
  hooks/hooks.json             names the hooks module
  hooks/register.tsx           the hooks: tool.call, turn.complete, command.run, ui.*
  hooks/blocks.ts              markdown to blocks; anchors and re-anchoring
  hooks/diff.ts                line diff, unified hunks, changed-block detection
  hooks/persist.ts             the shape of the per-document store record
  hooks/review-prompt.ts       the review, ask, escalation and approval texts
  types/index.d.ts             the state contract ($.state under 'doc-review')
  tests/review.test.ts         claude plugin test
docs/demo.gif, docs/demo.cast  the recording above
DESIGN.md                      the design and the reasoning behind it

Two engine rules matter when you edit the mod:

• $ is followed only into functions declared in the same file. A helper in another module can't take $, which is why persist.ts holds only shapes and the store calls live in register.tsx.
• An atom's reference must be written as string literals at the call site.

Deliberately not built

• A vim-style Client module (phase 3 of the design). Button hotkeys already cover every key on every surface. A Client only receives keys after a click gives it focus, and only on terminal and desktop.
• A draggable scrollbar. It was built as a Client and removed. Clicking a Client gives it the keyboard, so j, k and Tab stopped reaching the pane. The bar is now a row of Buttons, which can't trap the keys.
• Tests for hover. The test kit drops hover styling, so the hover reveal is type-checked and validated but not tested. The tests do press the hidden actions and check that each block has exactly one action row.