Skip to content
claudemods

Review Watch: a Claude Code Codex review monitor that shows running reviews live

A live line above the prompt for each running code review, Codex or a subagent, plus a findings toast when it ends.

Permissions

  • Reads filesCan read files and list directories on your machine ($.fs.read / list / stat / exists).
  • Runs commandsCan run shell programs on your machine ($.process.run / spawn). Check the source for exactly which ones.
  • Intercepts tool callsSees every tool call Claude makes (tool.call / tool.check) and could block or change it.
  • Changes the UIDraws into the Claude Code interface: bands, panes, status text, toasts (ui.render / $.ui.*).
tested with
v2.1.310
last tested
requires
Claude Code ≥ 2.1.287
surfaces
above-prompt, toast

Install inside Claude Code:

/plugin install review-watch --marketplace hamzafer/claude-code-mods
All install options ↓

What does this mod do?

Review Watch is a community mod by Hamza Zafar (hamzafer), part of his claude-code-mods collection. It is a Claude Code Codex review monitor: when a code review is running in the background, it answers "is it still going, and what is it doing?" without leaving the prompt.

Above the prompt it draws one line per running review. A line shows an icon, codex or agent, the model, what is under review, and the elapsed time. For Codex reviews a second, dimmed line shows the last line of Codex's output. When a review ends, a toast reports it with the elapsed time and the findings Codex listed, such as 2 findings (P1, P2) or no findings, and the line stays in the band with a check mark for 30 seconds.

What counts as a review:

  • A Codex review: a Bash command that runs codex review, or the Codex plugin's /codex:review and /codex:adversarial-review. The target is read from the command: --title, --commit, --base, or "uncommitted changes".
  • A review subagent: any subagent whose description contains the word review (not "preview" or "interview"). It is shown until that agent's turn completes.

The band shows up to four reviews and adds a +N more line for the rest.

Install

Use any of the methods in the install block; they install straight from the author's own marketplace. The band appears on the next session start and only while a review is running or has just finished.

$ install review-watch

Requires Claude Code ≥ 2.1.287

Installs from the author's own marketplace: hamzafer/claude-code-mods

  1. 1.One line, inside Claude Code

    /plugin install review-watch --marketplace hamzafer/claude-code-mods

    Paste into a running session (v2.1.275+). Claude Code asks to add the marketplace first.

  2. 2.From your shell

    claude plugin marketplace add hamzafer/claude-code-mods
    claude plugin install review-watch@claude-code-mods

    Then run /reload-plugins in any session that is already open.

  3. 3.Try it without installing

    git clone https://github.com/hamzafer/claude-code-mods
    claude --plugin-dir ./claude-code-mods/mods/review-watch

    Loads the mod for one session only. Nothing is added to your settings.

How it works

Reviews are kept in a host-held $.state atom, so they survive a hot reload. Subagents are caught on agent.spawn. This is from hooks/register.tsx:

on('agent.spawn', async ($, e, next) => {
  const r = await next(e)
  if (r.agentId && isReviewAgent(e.description ?? '')) {
    const one: Review = { id: r.agentId, kind: 'agent', model: e.model || r.model || 'inherit', label: e.description, status: 'running', startedAt: Date.now(), last: e.subagentType }
    await update($, reviews, list => [one, ...list.filter(v => v.id !== one.id)].slice(0, 20))
  }
  return r
})

A Codex review is recognized by a regular expression on the Bash command. The model comes from --model, -m or -c model= on the command line, and otherwise from the model line of ~/.codex/config.toml. The mod finds the review's output file from a > file redirect, or from the "written to: ….output" path Claude Code prints for a background shell. Every 3 seconds it lists processes with ps, checks whether the review's command line is still there, and reads the last 30 lines of the output file for the dimmed line. A clock that ticks once a second only updates the elapsed times while something is shown. The list is capped at 20 reviews.

Customize it

There are no options in /config and no commands. The look is set by constants at the top of register.tsx: SHOW_DONE_MS (how long a finished review stays, 30 seconds), BAND_ROWS (4), POLL_MS (3 seconds) and UNSEEN_POLLS (3). To control where the band sits relative to other band mods, the author's checklist mod saves an order file at <config dir>/claude-code-mods/bands.json; Review Watch reads it once per session, so restart Claude Code to apply a change.

Permissions & safety

We read every file the plugin can execute before running anything: .claude-plugin/plugin.json, hooks/hooks.json, hooks/register.tsx, hooks/bands.ts, the type declarations and the test file. There is no package.json, install script, binary, minified or encoded code. Findings:

  • Network: none. There is no fetch, socket or URL in the plugin. No telemetry.
  • Runs commands ($.process.run): ps -axww -o command= to list processes; tail on the review's output file (-n 30 and -c 40000, with -- before the path); and one sh -c that runs a fixed grep -E "^model *=" "$HOME/.codex/config.toml" | head -n 1. No part of your commands is put into a shell string. The ps output holds every process's command line; the mod only matches it against running reviews and does not store or show it.
  • Reads files: the output file of a review, which is the path your own command redirected to; ~/.codex/config.toml (the model line only); and the optional band-order file under CLAUDE_CONFIG_DIR or ~/.claude. It reads HOME and CLAUDE_CONFIG_DIR. The last line of a review's output file is shown in your terminal.
  • Writes files: none. It does not touch settings.json, shell files, LaunchAgents or git hooks. It starts no daemon; its two timers stop with Claude Code.
  • Hooks that intercept calls: tool.call for Bash and agent.spawn. Both only record the review and return the result of next(e) unchanged; neither denies, blocks or rewrites a call or a prompt. claude plugin validate notes that neither has a .catch, so an unexpected error in the mod could surface in those calls.
  • Model influence: none. It injects no text into prompts or tool results and uses no hidden Unicode.
  • License: MIT, with a LICENSE file at the repository root.

claude plugin validate reported no errors, plus one warning from the plugin-directory check (no icon). The author's 7 tests passed with claude plugin test on Claude Code 2.1.310.

Reads files
Can read files and list directories on your machine ($.fs.read / list / stat / exists).
Runs commands
Can run shell programs on your machine ($.process.run / spawn). Check the source for exactly which ones.
Intercepts tool calls
Sees every tool call Claude makes (tool.call / tool.check) and could block or change it.
Changes the UI
Draws into the Claude Code interface: bands, panes, status text, toasts (ui.render / $.ui.*).

Compatibility & troubleshooting

Checked with Claude Code 2.1.310 on macOS (validate and tests). We did not run a real Codex review. The process check uses ps -axww -o command=, so it is aimed at macOS and Linux. If the band does not show up:

  • Check that the command really starts with codex review (or the Codex plugin's review script). A review wrapped in a script of your own is not recognized.
  • A subagent is only tracked if its description contains the word review.
  • No Codex output line? The mod needs the output file: redirect with > review.txt or run it as a background shell, so that Claude Code prints the output path.
  • If the model shows default, add --model to the command or a model = "…" line to ~/.codex/config.toml.
  • A survey open above the input hides the band until it closes.

FAQ

Which reviews does Review Watch track?
Two kinds. A Bash command that runs `codex review` (including flags before `review`, and the Codex plugin's `codex-companion.mjs review` and `adversarial-review`), and a subagent whose description contains the word review, reviews, reviewer or reviewing. Other commands and subagents pass through untouched.
How does it know when a Codex review has finished?
If the command ran in the foreground, it is over when the Bash call returns. For a background run, the mod checks the process list with ps every 3 seconds and marks the review done once its command line is gone. If the process never shows up in ps, it gives up after 3 polls.
Where do the findings in the toast come from?
From the review's output file. The mod reads the last 40,000 bytes with tail and looks for Codex's "Full review comments:" block, then counts the `[P1]`, `[P2]` items. If it finds no such block but the text says there were no issues, it reports no findings. Otherwise the toast has no findings part.
Does it send my code or review output anywhere?
No. The plugin has no network calls. The only commands it runs are ps, tail and a grep of your Codex config, all locally, and what it reads is shown in your own terminal.
Does it work with other band mods such as Agent Radar?
Yes. It keeps what other mods draw above the prompt and adds its own band. If you use the author's band-order file, it sorts the bands by that order.
Agent Radar running in Claude CodeFeatured

Agent Radar

One live line above the prompt per running subagent: time, tool count and what it is doing now, plus a /radar pane.

  • above-prompt
  • pane
  • toast
  • Intercepts tool calls
  • Reads your prompts
  • Changes the UI
  • Adds commands/tools

tested with v2.1.291

Mission Control running in Claude CodeFeatured

Mission Control

A live pane of Claude Code's main agent, subagents and every tool call, plus a code map of the files they touch.

  • pane
  • above-prompt
  • Reads files
  • Writes files
  • Runs commands
  • Calls the model (uses your quota)
  • Intercepts tool calls
  • Changes the UI
  • Adds commands/tools

tested with v2.1.296

More in Git & GitHub, Toasts & notifications.