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
- source
- Hamza Zafar (hamzafer) (MIT)
Install inside Claude Code:
/plugin install review-watch --marketplace hamzafer/claude-code-modsWhat 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:reviewand/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.One line, inside Claude Code
/plugin install review-watch --marketplace hamzafer/claude-code-modsPaste into a running session (v2.1.275+). Claude Code asks to add the marketplace first.
2.From your shell
claude plugin marketplace add hamzafer/claude-code-mods claude plugin install review-watch@claude-code-modsThen run /reload-plugins in any session that is already open.
3.Try it without installing
git clone https://github.com/hamzafer/claude-code-mods claude --plugin-dir ./claude-code-mods/mods/review-watchLoads 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;tailon the review's output file (-n 30and-c 40000, with--before the path); and onesh -cthat runs a fixedgrep -E "^model *=" "$HOME/.codex/config.toml" | head -n 1. No part of your commands is put into a shell string. Thepsoutput 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 underCLAUDE_CONFIG_DIRor~/.claude. It readsHOMEandCLAUDE_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.callfor Bash andagent.spawn. Both only record the review and return the result ofnext(e)unchanged; neither denies, blocks or rewrites a call or a prompt.claude plugin validatenotes 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
LICENSEfile 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.txtor run it as a background shell, so that Claude Code prints the output path. - If the model shows
default, add--modelto the command or amodel = "…"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.
# Related mods
FeaturedAgent 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
FeaturedMission 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.