File Review

File Review

Unified skill for the file-review plugin. Routes to the correct workflow based on user intent.

Note: The /file-review and /process-comments commands are simple shortcuts for backward compatibility. They trigger the Review and Process workflows below. This skill is the canonical entry point.

Intent Router

Match the user's request to one of three workflows:

If the intent is ambiguous, use AskUserQuestion:

Install

Quick Install (Homebrew)

brew tap desplega-ai/tap
brew install file-review

Verify: which file-review

The Homebrew build is native-only — it does not include web mode. For --web/--tunnel you must build from source with bun run install:web (see Advanced: Web / tunnel mode).

Manual Install (from source)

Prerequisites: bun, Rust

git clone https://github.com/desplega-ai/ai-toolbox.git
cd ai-toolbox/file-review
bun install
bun run install:app   # native binary
# or, for web/tunnel mode:
bun run install:web   # web-feature binary

Both symlink to ~/.local/bin/file-review (ensure that's in PATH).

• bun run install:app builds the native (Tauri) binary. It does not include web mode — passing --web to it errors out (main.rs:101-105).
• bun run install:web builds the web-feature binary required for --web/--tunnel.
• Maintainers cutting a release use bun run release (handles version sync across the three manifests + build), not a bare install:*.

Troubleshooting

• Command not found: Ensure ~/.local/bin in PATH, restart terminal
• Rust not found: Restart terminal after installing Rust
• Build fails on macOS: xcode-select --install

Uninstall

cd ai-toolbox/file-review && bun run uninstall:app

Review a File

If no path provided

Check for recently created or modified files in the current session:

• Plan files in thoughts/<username|shared>/plans/
• Research documents in thoughts/<username|shared>/research/
• Any markdown files created or updated during the conversation

Pending review batches: also surface files that still contain active review-(start|line-start) markers — leftover review sessions whose comments were never processed:

grep -rlE '<!-- *review-(start|line-start)\(' thoughts/taras/ thoughts/shared/ --include="*.md" 2>/dev/null | head -20

Re-verify each hit against the Extraction Patterns regexes (Process Comments below) before proposing — a bare grep also matches files that merely quote the marker syntax (like this plan), so only offer files with a full parseable match.

Propose all candidates (recent files + pending batches) via a single multi-select AskUserQuestion. On selection, launch file-review "<p1>" "<p2>" … (0–N absolute paths, one tab each) and flow into Process Comments.

If path provided

1. Verify the file(s) exist and are readable.

2. Check if file-review is installed:

   which file-review
   

   If not found, jump to the Install section above.

3. Launch the GUI (one or more files):

   file-review "<p1>" "<p2>" …
   

   • The launch may pass 0–N absolute paths. Each positional path opens in its own tab (main.rs:50-56, lib.rs:23-48): one path → a single tab; multiple files → one tab per path.
   • Additional files can also be opened in-session: Cmd+T / Cmd+O (the file picker is multi-select) or drag-and-drop onto the window.
   • Use the Bash tool with run_in_background: true and timeout: 600000 (max allowed — 10 minutes)
   • Do NOT append & to the command — the process must block until the user closes the GUI
   • Do NOT use --bg — let the Bash tool handle backgrounding
   • When the background task completes, Claude is automatically notified and receives stdout (review comments)

   See Binary / CLI Reference below for all flags (--silent, --json, web mode, …) and the exact output formats.

4. Inform the user:

   I've opened file-review for <file(s)>.
   
   Shortcuts: Cmd+K (add comment), Cmd+T (new tab), Cmd+S (save), Cmd+Q (quit), Cmd+/ (help)
   

   No need to ask the user to notify you when done — you will be automatically notified when the GUI closes.

5. After the background task completes, the notification includes stdout with review comments:

   === Review Comments (N) ===
   
   [abc123] Line 15 (inline):
       "highlighted code"
       → Comment text here
   

   When multiple tabs were open, the output is grouped per file under ## <path> headers (see Binary / CLI Reference).

   Present the output, then proceed to Process Comments below.

Keyboard Shortcuts

Preview-mode vim navigation (j/k next/prev block, gg/G first/last, Ctrl+D/Ctrl+U page, / or Cmd+F search, n/N next/prev match) is listed in the in-app Cmd+/ shortcuts modal.

Binary / CLI Reference

file-review [OPTIONS] [FILE]... — mirrors file-review --help (main.rs:280-318).

Output formats (printed to stdout on close, unless --silent):

• Native, single tab — flat (comments.rs:151-179):

  === Review Comments (N) ===
  
  [abc123] Line 15 (inline):
      "highlighted code"
      → Comment text here
  

• Native, multiple tabs — grouped: each file's block is prefixed with a ## <path> header, blocks joined by blank lines (lib.rs:254-271):

  ## /tmp/a.md
  
  === Review Comments (1) ===
  …
  
  ## /tmp/b.md
  
  === Review Comments (1) ===
  …
  

• JSON (--json) (lib.rs:223-253): single tab → a bare array of comment objects; multiple tabs → an array of { "path", "comments": [...] } groups. Tabs with no comments are omitted.
• stdin mode (comments.rs:211-263): a combined block with === File ===, === Content ===, and === Review Comments === sections (the comments header becomes === Review Comments (content modified) === when the piped content was edited).

Advanced: Web / tunnel mode

Web mode serves the reviewer over HTTP instead of the native window — useful for remote review. It is explicitly single-file: run_web_mode takes one path (main.rs:143-174), so multi-file tabs are native-only.

file-review --web "<path>"                          # serve on http://127.0.0.1:3456
file-review --web --open "<path>"                   # also auto-open the browser
file-review --web --tunnel "<path>"                 # expose via localtunnel for remote access
file-review --web --tunnel --subdomain myname "<path>"
file-review --web --port 8080 "<path>"              # custom port (default 3456)

• --open and --tunnel require --web; --subdomain requires --tunnel.
• Comments come back exactly like the native close: when the page's Quit is triggered (browser/GUI close), the server re-reads the file, prints the comment block to stdout, and shuts down (web_server.rs:279-356). Feed that into Process Comments below.

Install caveat: web mode needs the web-feature build. A plain bun run install:app binary — and the Homebrew build — is native-only and rejects --web with Error: Web mode requires the 'web' feature (main.rs:101-105). Build the web binary from source:

cd ai-toolbox/file-review && bun run install:web

Because Homebrew is native-only, brew users who want web mode must build from source this way.

Config

Persistent settings live in ~/.file-reviewer.json (config.rs:11-22,44-48). Keys (must match the AppConfig struct):

file-review --help prints the config path and current contents; the in-app Cmd+/ shortcuts modal also exposes it.

Process Comments

Comment Format

The file-review tool embeds comments as HTML markers:

Inline comments:

<!-- review-start(ID) -->highlighted text<!-- review-end(ID): reviewer feedback -->

Line comments:

<!-- review-line-start(ID) -->
content spanning
multiple lines
<!-- review-line-end(ID): reviewer feedback -->

ID is an 8-character alphanumeric identifier.

Extraction Patterns

// Inline - captures: [full, id, highlighted, feedback]
/<!--\s*review-start\(([a-zA-Z0-9-]+)\)\s*-->([\s\S]*?)<!--\s*review-end\(\1\):\s*([\s\S]*?)\s*-->/g

// Line - captures: [full, id, highlighted, feedback]
/<!--\s*review-line-start\(([a-zA-Z0-9-]+)\)\s*-->\n?([\s\S]*?)\n?<!--\s*review-line-end\(\1\):\s*([\s\S]*?)\s*-->/g

Workflow

Step 1: Determine source and parse

The close-output (stdout returned when the GUI closes) is the source of truth for which files were reviewed and what the comments are. Consume that output directly; re-read a file from disk only if needed — when the run used --silent, when stdout was truncated, or when you need the exact on-disk spans to strip markers (apply the Extraction Patterns to the file content in that case).

• Single tab → flat === Review Comments (N) === block → process that one file (the default path).
• Multiple tabs → output grouped under ## <path> headers → parse each section into { path, comments }.

Present a per-file summary:

Found 5 review comments across 2 files:

thoughts/taras/plans/…plan.md (3):
  1. [inline] "implement caching" → "Consider using Redis"
  2. [line]   "function fetchData()…" → "Add error handling"
  3. …
thoughts/taras/research/…md (2):
  …

For a single file, collapse to the flat Found N review comments in <file>: form.

Step 2: Process each comment, grouped by file

Work one file at a time. For each comment, show context and use AskUserQuestion:

• Apply edit: draft the change for the highlighted span addressing the feedback, apply after confirmation, then strip the markers. (You may show a short before/after or 2-line unified diff first — keep it terse, not a ceremony.)
• Acknowledge: strip the markers, preserve content unchanged. Recommend for praise/FYI.
• Skip: leave marker and content as-is.

Step 3: Strip markers (on the on-disk file)

Edit each touched file directly, matching the captured full marker:

• Inline: replace <!-- review-start(ID) -->text<!-- review-end(ID): feedback --> with text.
• Line: replace the full block with just the inner content lines.

Process files sequentially (read → edit → next file) — never concurrent writes to one file.

Step 4: Final summary (per-file + totals)

Processing complete (2 files):

thoughts/taras/plans/…plan.md — Applied 1, Acknowledged 2, Skipped 0
thoughts/taras/research/…md   — Applied 0, Acknowledged 1, Skipped 0

Totals: Applied 1, Acknowledged 3, Skipped 0
All markers stripped from touched files; files saved.

For a single reviewed file, collapse to one flat block (Applied / Acknowledged / Skipped).

Special Cases

• FYI/Praise ("LGTM", "Nice work"): Recommend Acknowledge as default.
• Empty feedback: Ask if the user wants to remove the markers.
• Unclear feedback: Use AskUserQuestion to clarify reviewer intent before applying.
• Batch hint: when comments came from a multi-file batch, note "X of N markers from the same review session" in the per-comment prompt.