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

​
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 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 on the repo and sign in first: