CLI flags for programmatic review: diff selection, agent jobs, code tours, and headless daemon mode

[backnotprop]

Summary

The review UI has ~60 interactive capabilities — diff type switching, base branch selection, agent job launching, code tours, AI chat, PR navigation, conventional comments, and more. None of them are accessible from the CLI. Every review session starts with the defaults and requires manual interaction in the browser to change anything.

Now that we have a daemon, review sessions can run headlessly (no browser opened). This means the CLI should be the full programmatic interface to everything the UI can do.

Motivation

• CI/CD integration: kick off a review agent against a specific base commit without opening a browser
• Scripted workflows: plannotator review --base main --launch-agent claude --headless in a pre-merge hook
• Code tours: plannotator review PR_URL --launch-tour --headless generates a tour without manual UI interaction
• Reproducible reviews: share exact review parameters as CLI flags instead of "open the UI, click these 4 things"

Proposed CLI Flags

Diff selection

plannotator review --diff-type merge-base        # vs default uncommitted
plannotator review --base abc1234                 # specific commit as baseline
plannotator review --base main                    # branch as baseline
plannotator review --diff-type last-commit        # review the most recent commit
plannotator review --diff-type staged             # only staged changes

Agent jobs

plannotator review --launch-agent claude          # start Claude review agent
plannotator review --launch-agent codex           # start Codex review agent
plannotator review --launch-tour                  # start code tour agent
plannotator review PR_URL --launch-agent claude --launch-tour

Headless / daemon mode

plannotator review --headless                     # daemon session, no browser
plannotator review --headless --launch-agent claude --wait
                                                  # run agent, wait for result, print to stdout
plannotator review --headless --launch-tour --json
                                                  # run tour, output JSON result

AI configuration

plannotator review --ai-provider anthropic --ai-model claude-sonnet-4-6
plannotator review --ai-reasoning-effort high

Output

plannotator review --json                         # structured JSON output for session result
plannotator review --copy-diff                    # print raw diff to stdout
plannotator review --export-feedback              # print feedback markdown to stdout

How It Works With the Daemon

The daemon already owns session lifecycle. These CLI flags would:

1. Create a daemon session with the specified parameters pre-configured
2. In headless mode: skip openBrowser(), wait for agent/tour completion via waitForResult
3. In browser mode: open the UI with the parameters pre-selected (base branch, diff type already set)
4. For agent jobs: the daemon session factory would accept agent launch config and start jobs immediately after session creation

The review server already has all the API endpoints (/api/diff/switch, /api/agents/jobs, /api/tour/:id, etc.). The work is:

• Extend parseReviewArgs to accept the new flags
• Pass them through runDaemonSessionRequest into the session factory
• Add a headless mode that skips browser opening and waits for programmatic completion
• Wire agent launch into session creation so jobs start without UI interaction

Current State

Capability	UI	CLI
Diff type selection (7 types)	Dropdown picker	Not available
Base branch/commit selection	Interactive picker with SHA search	Not available
Launch review agent (Claude/Codex)	Button in sidebar	Not available
Launch code tour	Button in sidebar	Not available
View agent logs/output	Sidebar panel	Not available
AI chat with model selection	Sidebar tab	Not available
PR stack navigation	Tab switcher	Not available
Conventional comments	Label picker	Not available
File staging	Checkbox per file	Not available
Headless session (no browser)	N/A	Not available
Structured JSON output	N/A	Not available

Scope

Phase 1 (high value, low effort):

• --base <ref> and --diff-type <type> — pre-select diff parameters
• --headless — daemon session without browser

Phase 2 (agent automation):

• --launch-agent <provider> and --launch-tour
• --wait / --json for programmatic output
• Agent configuration flags (model, effort)

Phase 3 (full parity):

• AI provider/model selection
• Conventional comment support in structured input
• PR action flags (approve, comment, request-changes)

Related

• PR Move plugins to single binary runtime #733: Single binary runtime (CLI entry point)
• PR Add long-running Plannotator daemon runtime #734: Daemon runtime (session lifecycle)
• PR Add daemon WebSocket event hub #744: WebSocket event hub (live event transport)