Skip to main content
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.
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:
Each event is one line of JSON on stdout, so the stream pipes into another process unchanged:
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.
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), 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.
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

​
Event kinds

Every line carries a kind, the affected pr, an ISO createdAt, an opaque cursor, and a curated data object. 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 on the repository. Sign in to the GitHub CLI first: