Review a pull request

hwt review accepts one full GitHub pull request URL, pull request number, or branch reference:

hwt review https://github.com/owner/repository/pull/123
hwt review 123
hwt review origin/feature/name

The command never checks out or resets the primary checkout. It creates a local branch with the PR’s head branch name (or the selected branch name), creates the worktree through the normal HWT lifecycle, opens its Herdr workspace without taking focus, and starts the configured review command. Pass --focus to switch to the review workspace.

Pull requests and forks

Positive decimal selectors are always pull request numbers and are resolved in the current repository by gh. Pull request URLs must use HTTPS and exactly https://HOST/OWNER/REPO/pull/NUMBER, without a query, fragment, port, or userinfo. github.com is supported directly. A GitHub Enterprise host must match a configured Git remote. HWT queries metadata with authenticated gh, fetches the base repository’s refs/pull/NUMBER/head and base branch into private refs/hwt/reviews/ refs, and verifies that the fetched head SHA matches GitHub’s response. This synthetic head ref supports same-repository and fork pull requests while it remains available on the server.

With multiple remotes, HWT matches the URL’s host, owner, and repository. Use --remote NAME if that is not unique. --repo [HOST/]OWNER/REPO is passed to gh and must identify the repository in the URL.

Branch references

A local branch is treated as already fetched. REMOTE/BRANCH fetches that branch without changing a checkout. An unfetched plain branch works when there is an origin remote, or exactly one remote. With multiple remotes and no origin, use REMOTE/BRANCH or --remote NAME. Explicit remote selectors always fetch the branch. Detached primary HEAD is rejected for branch selectors because there is no unambiguous review base. Pull request URLs carry their base metadata and still work from detached HEAD.

Reuse

Pass --reuse to open an existing linked worktree or put an existing local branch in a new worktree. HWT preserves local commits and uncommitted changes; it never resets the branch to the fetched tip. JSON reports the actual checked-out commit. Without --reuse, a conflicting local commit or existing worktree is an error (--focus also permits opening an existing worktree at the requested commit). Reuse does not repeat file copies or post_create hooks. If the worktree is closed, HWT reopens it and launches the reviewer. If its Herdr workspace is already open and its recorded review pane is busy, HWT returns it with review_command.status set to already_open and does not start a duplicate process. If that pane is idle because the tool exited, HWT launches it again.

Generated worktree paths continue to use worktree_dir, worktree_naming, and worktree_prefix. New review worktrees receive the normal copied files, environment/port allocation, local DNS registration, and post_create hooks.

Review command and recovery

review_command is an argv array and defaults to [tuicr]. To open the fetched pull request directly in tuicr, configure [tuicr, pr, '{pr_url}']. HWT replaces an exact {pr_url} argument with the canonical pull request URL and shell-quotes every argument before Herdr runs it in the checkout. The placeholder is rejected when reviewing a branch rather than a pull request URL or number. Missing executables and Herdr launch failures return an error after reporting the successful workspace in JSON. The workspace remains intact so the tool can be installed or started manually. launched means Herdr accepted the command; later early exits or non-zero statuses do not remove the workspace.

One-off reviewer arguments

Append extra arguments without changing configuration by placing them after --. With the default [tuicr] command:

hwt review 123 -- pr '{pr_url}'
hwt review origin/feature/name -- -r main...HEAD

Each argument after -- appends exactly one argv entry after the configured arguments. Values are not split on spaces or commas, and shell syntax remains literal. Put HWT flags, such as --json and --reuse, before --; everything after it is passed to the reviewer, including values beginning with -. Exact {pr_url} entries expand to the canonical URL and are rejected for branch reviews, just like configured arguments. These arguments do not persist to configuration or restart an already-open review process; JSON reports the requested expanded command.

JSON output

hwt review --json https://github.com/owner/repository/pull/123

The result includes PR or branch identity, the verified commit and local review branch, checkout path, workspace and pane IDs, reused, and the review command’s argv, status, and optional error. On a launch failure HWT prints this recoverable result before returning a non-zero status.

Flags

Flag	Description
--cwd PATH	Repository path. Defaults to the current directory.
--remote NAME	Remote to fetch when selection is ambiguous.
-R, --repo REPOSITORY	GitHub repository for a PR URL or number in [HOST/]OWNER/REPO form.
--focus	Focus the created or reused workspace.
--reuse	Open an existing branch or worktree without resetting it.
--json	Print identity, checkout, workspace, reuse, and launch information.
-- ARGS...	Append literal arguments to the configured reviewer command.