CC Plan Reviewer

External browser reviewer for Claude Code plan mode.

The tool attaches to Claude Code's native plan flow through local command hooks. The command hook enriches Claude Code's hook payload with terminal metadata, forwards it to the local reviewer server, and returns the server's hook decision back to Claude Code. When Claude Code produces a plan through ExitPlanMode, the reviewer opens a local browser page where you can review the plan, add inline comments, request changes, or approve execution.

Quick Start

Install the CLI:

npm install -g cc-plan-reviewer

Run a local environment check:

cc-plan-reviewer doctor

Install or refresh the Claude Code hooks:

cc-plan-reviewer setup

If Claude Code is launched with a custom config directory, install the hooks into the settings file that Claude Code actually reads:

cc-plan-reviewer setup --settings /path/to/settings.json
cc-plan-reviewer setup --claude-config-dir /path/to/claude-config-dir

Start the local reviewer server:

cc-plan-reviewer start

Or install it as a macOS background service:

cc-plan-reviewer service install
cc-plan-reviewer service start

Check the current server and hook state:

cc-plan-reviewer status

Remove the hooks with:

cc-plan-reviewer clean

Then use Claude Code plan mode normally. When Claude calls ExitPlanMode, the reviewer opens a dedicated plan URL:

http://127.0.0.1:48731/plans/<review-id>

/reviews remains available as a convenience entry point. If a plan is already waiting, it redirects to the latest /plans/<review-id> page; otherwise it shows the waiting state.

From Source

When running from a cloned checkout, install dependencies first:

npm install

Then use the npm scripts:

npm run doctor
npm run setup
npm run start

Preview the hook settings change without writing anything:

npm run setup -- --dry-run

Run the release checks locally:

npm run publish:check

setup validates the local environment, writes the planner command hooks to ~/.claude/settings.json, and creates a timestamped backup before changing an existing settings file.

To preview a different target settings file:

npm run setup -- --settings ~/.config/quickswitch/claude/default-settings.json --dry-run

Decisions

• Request changes returns a deny decision with structured feedback. Claude Code remains in plan mode and can generate a revised plan.
• Approve & Execute returns an allow decision and Claude Code continues its native execution flow.
• Return to Claude Code returns an ask decision so the native Claude Code prompt can take over.

Multi-round review

When you click Request changes, the hook returns feedback to Claude Code and the TUI remains in plan mode. Claude can revise the plan and call ExitPlanMode again. The reviewer reuses the same browser page for the same Claude session and appends the new plan as another version. Multiple Claude Code sessions can review plans at the same time because each session has its own /plans/<review-id> page.

Open plan pages send a lightweight heartbeat to the local server. When Claude returns a revised plan for the same review, the server reuses the already open page instead of calling the system browser opener again. If the page has been closed or becomes stale, the next revised plan opens the review URL again.

After comments are submitted, the reviewer waits for a clear Claude Code signal instead of guessing with a timeout:

• another ExitPlanMode call means a revised plan is ready in the same browser page;
• AskUserQuestion means Claude is asking something in the TUI, so the page prompts you to return to Claude Code;
• Stop means the turn ended without a revised plan, so the page also prompts you to continue in Claude Code.

Commands

cc-plan-reviewer start
cc-plan-reviewer setup [--settings <file>] [--claude-config-dir <dir>]
cc-plan-reviewer clean [--settings <file>] [--claude-config-dir <dir>]
cc-plan-reviewer uninstall [--settings <file>] [--claude-config-dir <dir>]
cc-plan-reviewer doctor [--settings <file>] [--claude-config-dir <dir>]
cc-plan-reviewer install-hook [--settings <file>] [--claude-config-dir <dir>]
cc-plan-reviewer uninstall-hook [--settings <file>] [--claude-config-dir <dir>]
cc-plan-reviewer service install
cc-plan-reviewer service start
cc-plan-reviewer service stop
cc-plan-reviewer service restart
cc-plan-reviewer service status
cc-plan-reviewer service logs
cc-plan-reviewer status

The default port is 48731. Override it with:

CC_PLAN_REVIEWER_PORT=48732 npm run start

Override the default Claude settings target with:

CC_PLAN_REVIEWER_CLAUDE_SETTINGS=/path/to/settings.json cc-plan-reviewer setup

Using with quickswitch

If you launch Claude Code through quickswitch (qs), quickswitch generates a per-profile runtime settings file from:

~/.config/quickswitch/claude/default-settings.json

Install the reviewer hooks into that shared default settings file once:

cc-plan-reviewer setup --settings ~/.config/quickswitch/claude/default-settings.json

All future qs start claude ... sessions inherit the hooks when quickswitch generates their runtime settings.json.

To remove only the reviewer hooks from quickswitch:

cc-plan-reviewer clean --settings ~/.config/quickswitch/claude/default-settings.json

Background Service

On macOS, the reviewer can run as a LaunchAgent so you do not need to keep a separate terminal open:

cc-plan-reviewer service install
cc-plan-reviewer service start

The LaunchAgent plist is written to:

~/Library/LaunchAgents/com.nofrish.cc-plan-reviewer.plist

Logs are written under:

~/.cc-plan-reviewer/logs/

Useful service commands:

cc-plan-reviewer service status
cc-plan-reviewer service logs
cc-plan-reviewer service logs --follow
cc-plan-reviewer service logs --error
cc-plan-reviewer service stop
cc-plan-reviewer service uninstall

Uninstall

Remove only the Claude Code hooks:

cc-plan-reviewer clean

Remove Claude Code hooks and the macOS background service:

cc-plan-reviewer uninstall

Preview the uninstall without changing files:

cc-plan-reviewer uninstall --dry-run

The data directory is kept by default:

~/.cc-plan-reviewer/

Remove saved reviewer data, pasted-image attachments, and logs too:

cc-plan-reviewer uninstall --data

If you only want to remove the Claude Code hooks:

cc-plan-reviewer clean

Troubleshooting

Run the built-in diagnostic first:

cc-plan-reviewer doctor

Check whether the local reviewer server and hooks are visible:

cc-plan-reviewer status

If a plan does not open in the browser:

1. Start the server with cc-plan-reviewer start, or use cc-plan-reviewer service start.
2. Run cc-plan-reviewer status and confirm hooks show 3/3 installed.
3. Run cc-plan-reviewer setup to refresh the hook configuration.

If the background service is not behaving as expected:

cc-plan-reviewer service status
cc-plan-reviewer service logs
cc-plan-reviewer service logs --error
cc-plan-reviewer service restart

If Claude Code settings become invalid JSON, restore the timestamped backup created next to ~/.claude/settings.json, or manually remove the cc-plan-reviewer hook entries from that file.

Returning to the TUI

The Go back to TUI button focuses Ghostty on macOS by default. The hook bridge captures the focused Ghostty terminal id when the hook fires, but only keeps that id when the focused terminal's working directory matches Claude Code's hook cwd. This avoids jumping to a stale frontmost terminal when the hook is simulated or launched from a different context.

Focus order:

1. Focus the captured Ghostty terminal id.
2. Fall back to an exact Ghostty working-directory match.
3. Fall back to activating the configured terminal app.

Override the terminal app name with:

CC_PLAN_REVIEWER_TERMINAL_APP=iTerm npm run start

Precise iTerm2/Terminal.app/tmux targeting can use the same command-bridge metadata path later. Ghostty is implemented first because it is the local target terminal for this tool.