# 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
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, apart from an access check at most once every five minutes.

## Usage

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

```bash
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
{"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
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](https://pullfrog.com/docs/watch#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.

**Claude Code**:

```bash
claude mcp add pullfrog -- npx pullfrog mcp
```

**Codex**:

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

**OpenCode**:

```jsonc
{
  "mcp": {
    "pullfrog": {
      "type": "local",
      "command": ["npx", "pullfrog", "mcp"],
      "enabled": true,
      // milliseconds, and must exceed the longest pr_wait you ask for
      "timeout": 120000
    }
  }
}
```

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.

## 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.

| Setting | Effect |
| --- | --- |
| `--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](https://pullfrog.com/docs/getting-started) on the repository.

Sign in to the GitHub CLI first:

```bash
gh auth login
```
