> ## 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 completed check suite.

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

Pullfrog already receives the GitHub webhooks for your repository, so each event reaches you within a second of firing. The stream makes no GitHub API calls of its own; only a periodic access check does, at most once every five minutes.

## Usage

Run the command inside your repository, or name the repository:

```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 human-readable lines.

## Watching from an agent

The default command runs until you stop it, which suits a terminal or a harness that reads a long-running process's output. Most coding agents can only call something that returns, so Pullfrog offers two shapes that do.

### `--once`

With `--once`, the command waits for the next batch of activity, prints it, and exits. Any agent that can run a shell command can use it as a monitor.

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

It waits up to 20 seconds. If nothing happens, it exits 0 with no output, so a loop is repeated calls. Each call saves its position (see [Resuming](#resuming)), so the next call starts where the last one stopped.

### `pullfrog mcp`

The MCP server exposes the same wait as a tool named `pr_wait`, which blocks until something happens on the PR and returns it. Register the server once, and the agent can wait on a PR like any other tool call.

<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 is capped at 50. The call blocks, so the harness's MCP request timeout must be longer than the wait you ask for. The snippets above raise 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 enough to decide whether to react: actor, action, state, a truncated body or title, and the `html_url`. Fetch the full detail from that URL when you need it.

## Resuming

The stream is cursor-based. The last position is saved per repository and PR under `~/.pullfrog/watch/`, so a restarted watcher or the next `--once` call continues from where the previous one stopped.

Pullfrog buffers a PR's events only while a watcher has checked in within the last minute, and keeps buffered events for an hour. Events that arrive while nothing is watching are not delivered later, so keep `--once` calls less than a minute apart.

* `--since <cursor>` starts from a cursor you name, ignoring the saved one.
* `PULLFROG_STATE_DIR` moves the saved positions out of the home directory.

A watch that has never run for a PR starts from now rather than replaying history.

## Authentication

The command authenticates with your GitHub CLI token and streams events only for repositories that token can read. Pullfrog must be [set up](/getting-started) on the repository. Sign in to the GitHub CLI first:

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.