/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](#fetch-pending-reviews) and [Present Results](#present-results). Take the queue from the invoking context as given and dispatch each review in the order received. Everything from [Dispatch Review Sessions](#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 a