review-inbox

name	review:inbox
description	Dispatch inbound pull request reviews as background sessions that collect in `claude agents`. Use when reviewing multiple PRs, checking the review queue, batch reviews, or managing your review inbox across GitHub and GitLab. Pass --queue to dispatch an already-ordered queue.
argument-hint	[--queue]
disable-model-invocation	true
allowed-tools	["Monitor","TaskStop","Skill(gitlab:merge-request)","Bash(gh:*)","Bash(claude:*)","Bash(jq:*)","Bash(bun ${CLAUDE_SKILL_DIR}/scripts/:*)"]

Review Inbox

Dispatch inbound PR/MR reviews as background sessions. Each review runs as its own claude --bg --agent review <url> session, collected in the claude agents view. You fetch the pending queue and dispatch. Monitoring, completion, and worktree isolation belong to the agent view and the harness, not to you.

Arguments

• --queue: dispatch an already-triaged, ordered queue handed in by a caller, rather than fetching your own. Default: off, the interactive flow that fetches and presents the queue below.

Curated Queue

When --queue is set, another skill has already gathered, triaged, and ordered the reviews.

Skip Fetch Pending Reviews and Present Results. Take the queue from the invoking context as given and dispatch each review in the order received. Everything from Dispatch Review Sessions onward is unchanged.

Fetch Pending Reviews

Both fetches return the UNREVIEWED bucket: PRs/MRs awaiting your first review. Approving, requesting changes, or starting a review drops an item. A re-request re-adds it.

GitHub

gh search prs --review-requested=@me --state=open --json number,title,url,repository

GitLab

Load gitlab:merge-request and run its review-queue command for the UNREVIEWED MRs across all projects. It emits [{ url, reference, title }] as JSON. The query and its review-state filter are documented and owned by the gitlab plugin; the inbox only delegates to it.

Present Results

Combine results from both platforms into a summary table. Ask which reviews to start.

Dispatch Review Sessions

For each selected review:

Resolve the Local Repo Path

The review agent checks out the PR branch with gh pr checkout, so the session runs inside a local clone of the PR's repo. Ask where the repo is cloned. If it is not cloned, clone it first. The path is required to dispatch.

Dispatch

bun ${CLAUDE_SKILL_DIR}/scripts/spawn.ts <pr-url> --repo-path <local-path> --data-dir ${CLAUDE_PLUGIN_DATA}

spawn.ts runs claude --bg --agent review <pr-url> in the repo clone. The session collects in claude agents. On its first write (the review agent's gh pr checkout) the harness moves it into an isolated worktree, so parallel reviews never share a working tree. spawn.ts records the launched session in a dedup set and refuses a URL it has already dispatched, so a re-dispatch is a no-op.

Pass --permission-mode <default|acceptEdits|plan|bypassPermissions> to set the dispatched session's permission mode. Omit it to keep Claude's default.

Monitor

Reviews collect in the agent view. Manage them there, not here:

• claude agents (or the ca alias) opens the live view, grouped into needs-input, working, and completed.
• claude agents --json lists sessions for scripting.
• claude logs <id>, claude attach <id>, and claude stop <id> inspect or control one session.

To see what this inbox has dispatched and cross-reference session ids:

bun ${CLAUDE_SKILL_DIR}/scripts/dispatched.ts list --data-dir ${CLAUDE_PLUGIN_DATA}

Lifecycle

A dispatched review runs to completion on its own and cleans up its own worktree. The inbox does not track or reclaim it. The dedup set only prevents double-dispatch. Manage it directly when needed:

• dispatched.ts --reset --data-dir ${CLAUDE_PLUGIN_DATA} clears the set at the start of a fresh inbox session, so a re-requested review can dispatch again.
• dispatched.ts remove --url <pr-url> --data-dir ${CLAUDE_PLUGIN_DATA} untracks a single review.

When you have dispatched the selected queue, present a summary of what you sent and point at claude agents for progress.

Monitor Loop (Hands-Off)

The interactive flow above is the default: fetch once, present, ask, dispatch. The loop is the opt-in hands-off mode. It polls the UNREVIEWED queues on an interval and dispatches a session for each newly-arrived review without prompting, so the queue drains itself while you work elsewhere.

Wire the Review-Queue Sources

poll.ts knows no platforms. Each --queue is a command that emits an UNREVIEWED queue as [{ url }] JSON. Pass one per platform you want polled, and omit the rest:

• GitHub: gh search prs --review-requested=@me --state=open --json url.
• GitLab: load gitlab:merge-request and pass bun <ABS>, where <ABS> is the absolute path the gitlab docs resolve to for scripts/review-queue.ts (for example /Users/you/.claude/plugins/cache/.../gitlab/skills/merge-request/scripts/review-queue.ts). Write the resolved path out in full. Do not reuse ${CLAUDE_SKILL_DIR} from the examples below: it points at this inbox skill, not gitlab, so it resolves to the wrong directory.

Arm the Monitor

Pass this command to Monitor with persistent: true and a descriptive label. watch.ts runs a single long-lived bun process: each iteration it reads the dedup set, fetches all --queue sources, and prints one URL per line per newly-arrived review. Each printed URL is one event. ${CLAUDE_SKILL_DIR} below is the inbox's own directory, where watch.ts lives:

bun ${CLAUDE_SKILL_DIR}/scripts/watch.ts \
  --data-dir ${CLAUDE_PLUGIN_DATA} \
  --interval 300 \
  --queue "gh search prs --review-requested=@me --state=open --json url" \
  --queue "bun <ABS>"

A failed source emits a {"type":"source-error",...} line to stderr and contributes zero URLs, so one source's outage never stalls the loop. It is not suppressed.

Monitor Reliability

Two rules for any command you hand Monitor:

• Pass a single long-lived process that sleeps internally via setTimeout, not a shell while/sleep loop. This is a temporary workaround for a macOS Monitor bug: the eval context strips PATH (so sleep and date are not found) and kills backgrounded children with nice(5) failed: operation not permitted. When that harness bug is fixed, shell loops work again.
• Never suppress poll output with >/dev/null or || true. A silent poll is indistinguishable from "nothing new". Emit a structured line on error so failures are visible.

React to Each Event

For each emitted URL, dispatch a session without prompting, reusing Resolve the Local Repo Path. In unattended runs there is no one to answer the clone prompt, so skip any review whose repo is not cloned locally and report it rather than blocking the loop.

Pacing and Stopping

• A 300s interval is a reasonable floor: reviews arrive over minutes-to-hours and the queue sources hit rate-limited remote APIs.
• Call TaskStop on the Monitor task to stop early. Otherwise keep polling until told to stop (a re-request can re-add a review anytime).