follow

Watch PRs for status changes and get notified when something changes.

When you’re tracking PRs you’ve delegated, reviewed, or are otherwise interested in, follow monitors them for changes like CI passing, approval, merge conflicts, or new commits.

When to Use

Track delegated PRs you’ve sent for review
Watch a PR you’re waiting to merge
Monitor PRs where you need to know when CI passes
Keep tabs on PRs without cluttering your review queue

Synopsis

prctrl follow <ACTION> [OPTIONS]

Actions

Action	Description
`add`	Add PR(s) to your follow list
`list`	Show all PRs you’re currently following
`remove`	Remove PR(s) from your follow list
`clear`	Clear all followed PRs
`status`	Check for status changes since last check

Options

Flag	Description	Default
`<PR_NUMBER>`	PR number to follow (shorthand for `--pr`)	Optional
`-p, --pr <NUM>`	PR number to follow (shorthand for `--pr-numbers` with single value)	Optional
`--pr-number <NUM>`	PR number to follow (shorthand for `--pr-numbers` with single value)	Optional
`--pr-numbers <NUMS>`	PR number(s) to follow (comma-separated, format: `repo#123` or `123`)	Optional
`--json`	Output as JSON for scripting	`false`
`--repo`	Filter by repository name (partial match, case-insensitive). For `add`: filters which PRs are shown in interactive picker. For `list`/`remove`: filters followed PRs.	`none`
`--author`	Filter by author username (partial match, case-insensitive). For `add`: filters which PRs are shown in interactive picker. For `list`/`remove`: filters followed PRs.	`none`
`--priority` / `-P`	Show priority indicator based on PR size (🟢 SMALL, 🟡 MEDIUM, 🔴 LARGE)	`false`
`--since-days` / `-s`	Only show PRs created since this many days ago (for `add`: filters pending reviews; for `list`/`remove`: filters followed PRs by follow date)	`none`

PR Format

PRs can be specified in two ways:

Full format: repo#123 (e.g., frontend#4821)
Short format: 123 (uses first repo from config)

Examples

# Add a PR to your follow list
prctrl follow add 123

# Follow a PR using --pr flag (consistent with other commands)
prctrl follow add --pr 123

# Follow a PR using --pr-numbers flag
prctrl follow add --pr-numbers 123

# Follow multiple PRs
prctrl follow add 123,456,789

# Follow PRs across different repos
prctrl follow add frontend#4821,backend#1024

# Add: Show only PRs from a specific repo in interactive picker
prctrl follow add --repo frontend

# Add: Show only PRs from a specific author in interactive picker
prctrl follow add --author alice

# Add: Filter by both repo and author
prctrl follow add --repo frontend --author alice

# Add: Follow only recent PRs (created in last 7 days)
prctrl follow add --since-days 7

# List all followed PRs
prctrl follow list

# List followed PRs with priority indicators
prctrl follow list --priority

# List followed PRs as JSON (for scripting)
prctrl follow list --json

# List followed PRs for a specific repo
prctrl follow list --repo frontend

# List followed PRs by a specific author
prctrl follow list --author alice

# List followed PRs filtering by both repo and author
prctrl follow list --repo frontend --author alice

# Remove a PR from following
prctrl follow remove 123

# Remove all followed PRs by a specific author
prctrl follow remove --author alice

# Clear all followed PRs
prctrl follow clear

# Check for status changes
prctrl follow status

# Check for status changes for a specific repo
prctrl follow status --repo backend

# Check for changes and output as JSON
prctrl follow status --json

Tracked Changes

The status command detects:

Change	What It Means
Status changed	PR opened → merged/closed/draft
New commit	Author pushed new changes
CI status	CI pipeline passed/failed/pending

Output

👁️  Following 3 PR(s)
──────────────────────────────────────────────────
🟢 myorg/frontend #123 — Add user authentication  🟢 SMALL (365 lines)
    📊 +340/-25 lines  |  CI: ⏳  |  Review: ─  |  Author: alice
🟢 myorg/backend #456 — Fix database connection pool  🔴 LARGE (1400 lines)
    📊 +1200/-200 lines  |  CI: ✅  |  Review: 🔁  |  Author: bob
📝 myorg/frontend #789 — WIP: Dark mode support  🟢 SMALL (60 lines)
    📊 +50/-10 lines  |  CI: ✅  |  Review: ✅  |  Author: carol

Status Check Output

🔍 Checking status of 3 followed PR(s)...

  🔔 myorg/frontend #123 — Add user authentication
      Status: open → merged

  🔔 myorg/backend #456 — Fix database connection pool
      CI: pending → success

  ✅ No changes detected in followed PRs.

JSON Output

When using --json, the output is structured for scripting:

follow list --json returns an array of followed PRs:

[
  {
    "repo": "myorg/frontend",
    "pr_number": 123,
    "pr_title": "Add user authentication",
    "pr_url": "https://github.com/myorg/frontend/pull/123",
    "followed_at": "2026-03-27T10:00:00Z",
    "last_check": "2026-03-28T02:00:00Z",
    "last_known_state": "open",
    "last_ci_status": "pending",
    "last_review_state": "none",
    "last_commit_sha": "abc1234",
    "additions": 340,
    "deletions": 25,
    "author": "alice",
    "draft": false
  }
]

follow status --json returns an array of changes detected:

[
  {
    "repo": "myorg/frontend",
    "pr_number": 123,
    "pr_title": "Add user authentication",
    "state_changed": true,
    "old_state": "open",
    "new_state": "merged",
    "ci_changed": false,
    "old_ci": "pending",
    "new_ci": "pending",
    "has_new_commit": false,
    "old_commit": "abc1234",
    "new_commit_sha": "abc1234"
  }
]

How It Works

Add stores PR metadata (title, URL, author, size, last known state) in .followed.json
Status fetches current state and compares with stored state
Changes are reported and the stored state is updated
No notifications are sent (just local comparison) — combine with monitor for notifications

Storage

Followed PRs are stored in:

<review_output_dir>/.followed.json

monitor — Continuous monitoring with macOS notifications
digest — Daily digest of pending reviews
list — List all pending reviews

Keyboard shortcuts

PRCtrl