> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pullfrog.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Watch a PR

> Stream a pull request's reviews, comments and checks to your terminal or to a coding agent, without polling GitHub.

Pullfrog streams a pull request's activity to your terminal — one structured event per new review, comment, inline review thread, PR state change, or check-suite completion.

```bash theme={null}
npx pullfrog watch --pr 42
```

Pullfrog already receives every relevant GitHub webhook, so events are fanned out to you the instant they fire, with sub-second latency. The stream itself makes no GitHub API calls; only the periodic access re-check does, at most once every five minutes.

## Usage

Run it from inside your repo, or name the repo explicitly:

```bash theme={null}
npx pullfrog watch --pr 42              # infers the repo from the origin remote
npx pullfrog watch owner/repo --pr 42
```

Each event is one line of JSON on stdout, so the stream pipes into another process unchanged:

```json theme={null}
{"cursor":"11022","repo":"pullfrog/app","pr":1267,"kind":"check","createdAt":"2026-08-28T22:05:55.334Z","data":{"app":"GitHub Actions","status":"completed","headSha":"d9eeb89406c21c91d42bcf1ebcddb72a424df8c2","conclusion":"success"}}
```

Add `--pretty` for a human-readable line instead.

## Watching from an agent

Coding agents consume calls that return, not streams. The default command is a daemon that runs until you kill it, which suits a terminal or a harness that can read a long-running process's stdout — but most agents cannot consume that shape at all.

Two surfaces cover them.

### `--once`

Blocking single-shot mode: wait for the next batch of activity, print it, exit. Any agent that can run a shell command can use this as a monitor.

```bash theme={null}
npx pullfrog watch --pr 42 --once
```

It blocks for up to 20 seconds. If the PR goes quiet it exits 0 having printed nothing, so a loop is just repeated calls. Position is remembered between calls (see [Resuming](#resuming)), so nothing that lands between two calls is missed.

### `pullfrog mcp`

An MCP server exposing the same primitive as a tool called `pr_wait`, which blocks until something happens on the PR and returns it. Register it with your agent once and the agent can wait on a PR the same way it calls any other tool.

<CodeGroup>
  ```bash Claude Code theme={null}
  claude mcp add pullfrog -- npx pullfrog mcp
  ```

  ```toml Codex theme={null}
  # ~/.codex/config.toml
  [mcp_servers.pullfrog]
  command = "npx"
  args = ["pullfrog", "mcp"]
  tool_timeout_sec = 120  # must exceed the longest pr_wait you ask for
  ```

  ```json opencode theme={null}
  {
    "mcp": {
      "pullfrog": {
        "type": "local",
        "command": ["npx", "pullfrog", "mcp"],
        "enabled": true,
        // milliseconds, and must exceed the longest pr_wait you ask for
        "timeout": 120000
      }
    }
  }
  ```
</CodeGroup>

The tool takes the PR number, an optional `repo` as `owner/repo`, and an optional `max_wait_seconds` that defaults to 20 and caps at 50. Because the call blocks, your harness's MCP request timeout has to be longer than the wait you ask for — the snippets above set it where the default is too low.

## Options

| Flag               | Description                                        |
| ------------------ | -------------------------------------------------- |
| `--pr <number>`    | pull request number to watch (required)            |
| `--once`           | wait for one batch of events, print it, and exit   |
| `--since <cursor>` | resume from a cursor instead of the saved position |
| `--pretty`         | human-readable output instead of JSON lines        |
| `-h, --help`       | show help                                          |

## Event kinds

Every line carries a `kind`, the affected `pr`, an ISO `createdAt`, an opaque `cursor`, and a curated `data` object.

| Kind             | Fires on                                                              |
| ---------------- | --------------------------------------------------------------------- |
| `pr`             | pull request opened / closed / synchronized / edited / labeled / etc. |
| `review`         | a review submitted, dismissed, or edited                              |
| `review_comment` | an inline review comment created, edited, or deleted                  |
| `review_thread`  | an inline review thread resolved or unresolved                        |
| `comment`        | a top-level comment on the PR                                         |
| `check`          | a check suite completed (carries `status` + `conclusion`)             |

The `data` object holds just enough to decide whether to react — actor, action, state, a truncated body or title, and the `html_url`. Fetch full detail on demand from that URL.

## Resuming

The stream is cursor-based, and the last position is saved per repo and PR under `~/.pullfrog/watch/`. A restarted watcher, or a series of separate `--once` calls, picks up exactly where the previous one stopped without replaying what it already handled.

Two overrides:

* `--since <cursor>` starts from a cursor you name, ignoring the saved one.
* Setting `PULLFROG_STATE_DIR` moves the saved position somewhere other than the home directory.

A watch that has never run for a PR starts from now rather than replaying history. Buffered events expire after an hour, so a watcher that was off for longer resumes from the present.

## Authentication

Authentication uses your GitHub token from the GitHub CLI, and only streams events for repositories that token can read. Install the [GitHub App](/github) on the repo and sign in first:

```bash theme={null}
gh auth login
```