PRCtrl

Stop drowning in PR notifications. Let AI triage your reviews.

PRCtrl is your terminal-native PR companion. It watches your GitHub PRs, notifies you when action is needed, and helps you review smarter with AI-powered triage.

┌─────────────────────────────────────────────────────────────┐
│  🔔 PR #4821: feat: add CSV export                        │
│  PRCtrl                                         │
│  👤 alice • +120 lines • opened 2 days ago                 │
│                                                             │
│  ✅ Chrome opens automatically → PR ready for review       │
└─────────────────────────────────────────────────────────────┘

Why PRCtrl?

• No more tab switching — Everything in your terminal
• AI-powered triage — Let Claude analyze PRs for you
• Smart notifications — macOS native alerts, auto-opens PRs
• 30+ commands — From quick glances to deep dive analysis

Installation

cargo install --git https://github.com/JeremySomsouk/prctrl

Quick Start

# 1. Configure your GitHub credentials
prctrl config init

# 2. See what needs your attention
prctrl list

# 3. Let AI triage the important ones
prctrl delegate

# 4. Monitor in background (get notified of new PRs)
prctrl monitor &

Your First Review Workflow

# See all PRs waiting for you
prctrl list

# Output:
# 🔍 3 pending review(s)
#   [1] feat: add CSV export        #4821 (frontend)  👤 alice +120 - 2 days
#   [2] fix: flaky CI              #312 (backend)    👤 bob   +45  - 4 days
#   [3] chore: update deps         #891 (deps)       👤 carol +890 - 1 day

# Want to focus on important stuff only?
prctrl quick --max-lines 200

# Search for a specific PR?
prctrl search "security"

# Let Claude decide what's important?
prctrl delegate

Common Workflows

Morning Check (5 seconds)

prctrl summary
# Output: "📊 12 PRs pending • Oldest: 5 days • 3 urgent • 2 quick wins"

Before a Meeting

# Grab the essentials
prctrl top --limit 5

# Check if any have failing CI
prctrl ci --failed-only

Deep Work Session

# Start monitoring (you'll be notified of new PRs)
prctrl monitor --interval 300 &

# When you get a notification...
prctrl review --pr 4821  # Read the diff without leaving terminal
prctrl diff --pr 4821     # See stats

# Approve directly from CLI
prctrl approve --pr 4821 -m "LGTM! Good tests."

End of Week

# Generate a report of what you reviewed
prctrl report --days 7

# See your activity
prctrl activity --days 7

Configuration

Interactive Setup

prctrl config init

This creates a configuration file at ~/.prctrl/config.toml:

[github]
token = "ghp_xxxxxxxxxxxxxxxxxxxx"
username = "john_doe"
org = "my-company"
repos = ["frontend", "backend"]
teams = ["platform", "backend"]  # optional

Environment Variables (Alternative)

Instead of a config file, you can use environment variables:

# Required
PRCTRL_GITHUB_TOKEN=ghp_xxxxxxxxxxxx
PRCTRL_GITHUB_USERNAME=john_doe
PRCTRL_GITHUB_ORG=my-company
PRCTRL_GITHUB_REPOS=frontend,backend

# Optional
PRCTRL_GITHUB_TEAMS=platform,backend
PRCTRL_CREW_MEMBERS=alice,bob,carol
PRCTRL_ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx

Getting a GitHub Token

1. Go to GitHub → Settings → Developer Settings → Personal Access Tokens
2. Generate New Token (Classic)
3. Select scopes: repo, read:user, notifications
4. Add the token to your config or environment

All Commands

Core Commands

Taking Action

Finding PRs

Information

Background Monitoring

Utilities

Global Flags

These work with most commands:

License

MIT — Jeremy Somsouk

list

List all PRs waiting for your review or where you’ve commented.

This is your starting point. Shows every PR where you’re requested as a reviewer, plus PRs where you’ve already commented (so you can easily revisit your feedback). Sorted by oldest first.

When to Use

• Morning check: “What needs my attention today?”
• Before a meeting: “Any urgent PRs I should know about?”
• After returning from vacation: “What did I miss?”

Synopsis

prctrl list [OPTIONS]
prctrl ls [OPTIONS]     # shorthand alias

Options

Examples

# See everything waiting for you
prctrl list

# Find recent PRs only (last 7 days)
prctrl list --since-days 7

# With priority scores (oldest + largest = highest priority)
prctrl list --priority

# Filter to one repo
prctrl list --repo frontend

# Filter by author
prctrl list --author alice

# Combine filters
prctrl list --repo api --author bob --priority

# JSON output for scripts
prctrl list --json | jq '.[] | select(.author == "alice")'

# Show specific PR by number (via global --pr flag or local flag)
prctrl list --pr 4821
prctrl list -p 4821

# Show multiple PRs by number
prctrl list --pr-numbers 4821,3156

# Show only PRs where you have commented
prctrl list --commented

# Show PRs with stacked PR detection
prctrl list --show-stacks

# Combine with other filters
prctrl list --repo api --show-stacks --priority

Output Example

🔍 4 pending review(s)

[1] feat: add dark mode          #4821 (frontend)  👤 alice  +89   2 days
[2] fix: login timeout           #3156 (backend)   👤 bob    +234  4 days ⭐⭐⭐
[3] refactor: clean API          #2890 (shared)    👤 carol  +12   1 day
[4] chore: bump deps             #4521 (deps)      👤 dave   +890  5 days

Tips

• PRs are sorted oldest-first so you don’t miss stale reviews
• Use --priority to surface the most urgent ones visually
• Combine with --repo to focus on one codebase at a time
• Use --show-stacks to see PRs that build on each other (stacked PRs)

Stack Detection

When --show-stacks is enabled, list detects stacked PRs — PRs where one PR’s base branch is another PR’s head branch. This helps identify dependent PRs that need to be reviewed in sequence.

Example stack output:

┌─ Stack on `main` (3 PRs)

🔵 #123 - Add new feature
  └─ @feature
    https://github.com/owner/repo/pull/123

  #124 - Implement API endpoint
  └─ @feature-2
    https://github.com/owner/repo/pull/124

  #125 - Add tests
  └─ @feature-3
    https://github.com/owner/repo/pull/125

Stack detection works by analyzing branch relationships:

• PR targeting branch feature is the base
• PR targeting branch feature-2 builds on it
• This creates a stack that should be reviewed in order

delegate

Ask Claude to triage each pending review — AI-powered PR analysis.

Let Claude Code analyze your PRs, summarize changes, identify risks, and recommend actions.

When to Use

• Morning triage: “Which PRs should I prioritize?”
• Before deep work: “Quick summary of what’s waiting”
• Risk assessment: “Does this security-related PR need extra scrutiny?”

Synopsis

prctrl delegate [OPTIONS]
prctrl del [OPTIONS]       # shorthand alias

Options

Examples

# Interactive: select PR(s) to delegate
prctrl delegate

# Target a specific PR (global --pr flag)
prctrl delegate --pr 4821

# Preview what would be delegated (no actual delegation)
prctrl delegate --dry-run

# Preview specific PR without delegating
prctrl delegate --pr 4821 --dry-run

# Preview delegation with priority scores to identify urgent PRs first
prctrl delegate --dry-run --priority

# Only delegate recent PRs (last 7 days)
prctrl delegate --since-days 7

# Only delegate PRs from a specific repo
prctrl delegate --repo frontend

# Only delegate PRs from a specific author
prctrl delegate --author alice

# Combine filters for targeted delegation
prctrl delegate --repo api --author bob --dry-run

# JSON output for scripting
prctrl delegate --json

# Delegate all matching PRs without prompting (useful for scripts)
prctrl delegate --all

# Delegate all PRs from a specific repo without prompting
prctrl delegate --all --repo frontend

# Delegate specific PR and get JSON result
prctrl delegate --pr 4821 --json

# Quiet mode - suppresses per-PR output for cleaner batch processing
prctrl delegate --all --quiet

# Delegate multiple PRs at once with --pr-numbers
prctrl delegate --pr-numbers 4821,4822,4823 --all

Output

Interactive Mode (default)

Each delegation shows:

• Delegation progress indicator
• Summary from Claude
• Review file saved to output directory

JSON Mode

Returns an array of results with:

[
  {
    "pr_number": 4821,
    "pr_title": "feat: add dark mode",
    "repo": "frontend",
    "url": "https://github.com/org/frontend/pull/4821",
    "success": true,
    "summary": "Summary text from Claude",
    "error": null
  }
]

Tips

• Create instruction.md for project-specific review criteria
• Use --dry-run to verify targeting before committing to delegation
• Use --json for automation scripts or piping to other tools
• All PRs are delegated in parallel for speed (both modes)
• Progress feedback shows completion status for each PR as it finishes
• Combine filters (--since-days, --repo, --author) with --dry-run to preview targeted delegation
• Snoozed PRs are automatically excluded (consistent with list command)
• When --pr is combined with --repo, --author, or --since-days, the PR must match all filters to be selected (filters take precedence over direct fetch)

mine

List your own open PRs — draft or not.

Track your own pull requests from the command line.

When to Use

• Status check: “What’s my open PRs?”
• Draft management: “Find all my draft PRs”

Synopsis

prctrl mine [flags]

Flags

• --json — Output as JSON (useful for scripting)
• -a, --all — Show all matching PRs at once (without prompting)
• -P, --priority — Show priority score (1-5 stars) based on age and size
• -s, --since-days <DAYS> — Only show PRs created since this many days ago
• --repo <REPO> — Filter by repository name (partial match, case-insensitive)
• --author <AUTHOR> — Filter by author username (partial match, case-insensitive)
• -p, --pr <PR_NUMBER> — Target a specific PR by number
• --pr-numbers <NUMBERS> — Target multiple PRs by number (comma-separated, e.g., 123,456,789)

Stack Detection

The mine command automatically detects and displays stacked PRs — PRs that build on each other. Stacks are shown after your individual PR list.

Detection methods

PRCtrl uses two methods to detect stacked PRs:

1. Branch chaining — A PR’s base branch is another PR’s head branch:

• PR A: feature → main
• PR B: feature-2 → feature
• This creates a stack: PR A → PR B

2. Convention — PRs sharing the same ticket key with [N/M] position markers:

• PR #1: refactor(TAHC-1666): add client [1/3] on branch TAHC-1666-client
• PR #2: refactor(TAHC-1666): add service [2/3] on branch TAHC-1666-service
• PR #3: refactor(TAHC-1666): add tests [3/3] on branch TAHC-1666-tests
• These are grouped into a stack by the TAHC-1666 ticket key

Example stack output:

┌─ Stack on `main` (3 PRs, branch-chain)

🔵 [1/3] #974 - refactor(TAHC-1666): extract OnboardingCmsClient port [1/3] [DRAFT]
  └─ TAHC-1666-onboarding-cms-client-port
    https://github.com/doctolib/health-content/pull/974

  [2/3] #975 - refactor(TAHC-1666): extract OnboardingCompletionChecker port [2/3] [DRAFT]
  └─ TAHC-1666-onboarding-completion-checker
    https://github.com/doctolib/health-content/pull/975

  [3/3] #976 - refactor(TAHC-1666): extract OnboardingDebugController [3/3] [DRAFT]
  └─ TAHC-1666-onboarding-debug-controller
    https://github.com/doctolib/health-content/pull/976

Global Flags

These flags are available globally and work with mine:

• -p, --pr <PR_NUMBER> — Target a specific PR by number (overrides filters)
• -d, --include-drafts — Include draft PRs in results
• --exclude-prefix <PREFIXES> — Exclude PRs with matching title prefixes (comma-separated)
• -o, --output-dir <PATH> — Folder for review files (default: ./reviews)

Snooze Behavior

Snoozed PRs are automatically hidden from mine results (consistent with list and delegate). Use --pr, --pr-number, or --pr-numbers to bypass this filter and view specific snoozed PRs.

Examples

# List your open PRs
prctrl mine

# Show all PRs at once (non-interactive)
prctrl mine --all

# Show your PRs with priority scores
prctrl mine --priority

# Get JSON output for scripting
prctrl mine --json

# Include draft PRs
prctrl mine -d

# Only show PRs from the last 7 days
prctrl mine --since-days 7

# Filter by repository
prctrl mine --repo my-repo

# Filter by author
prctrl mine --author johndoe

# Target a specific PR (bypasses snooze filter)
prctrl mine --pr 123

# Target multiple specific PRs
prctrl mine --pr-numbers 123,456,789

# Combine filters
prctrl mine --since-days 14 --repo api --priority

# Combine with global flags
prctrl mine --include-drafts --priority

stats

Show review statistics: pending count, average wait time, and breakdowns by repository and author.

Gives you a high-level overview of your review queue at a glance.

When to Use

• Morning overview: “How bad is it?”
• Sprint planning: “What’s the review load?”

Synopsis

prctrl stats [OPTIONS]
prctrl stat [OPTIONS]      # shorthand alias

Options

Note: The global --pr flag (-p) also works with this command for consistency with other commands.

Examples

# See all review statistics
prctrl stats

# Stats as JSON for scripting
prctrl stats --json

# Stats for a specific repo only
prctrl stats --repo frontend

# Stats filtered by author
prctrl stats --author alice

# Stats for a specific PR
prctrl stats 4821
prctrl stats --pr 4821

# Stats with priority breakdown (includes most urgent PR highlight)
prctrl stats --priority

# Stats for PRs created in the last 7 days only
prctrl stats --since-days 7

# Stats for all matching PRs without interactive selection
prctrl stats --all

# Preview which PRs would be included in stats
prctrl stats --dry-run

# Combine --all with filters
prctrl stats --all --repo frontend --priority

Output

Normal Mode

• Total pending reviews count
• Total lines changed (+additions / -deletions)
• Average time waiting
• Oldest PR info
• Breakdown by repository (sorted by count)
• Breakdown by author (with visual bar chart)

Priority Mode (--priority)

When --priority is enabled, stats also shows:

🚨 Most Urgent — A highlighted callout showing the single PR that demands your immediate attention, including:

• PR title and number with priority stars
• Author, size, age, and repository
• Direct link to the PR

Priority Breakdown — PRs grouped by score (1-5 stars):

• Shows count of PRs at each priority level
• Oldest PR age within each group
• Total lines changed per group

This helps you understand both the overall queue health and the most critical item needing action.

Dry-Run Mode

When using --dry-run, the command shows a preview of which PRs would be included in the stats without actually computing or displaying the statistics. This is useful for:

• Checking which PRs match your filters before running full stats
• Verifying filter criteria are correct
• Quickly listing matching PRs

team-summary

Show team review summary — how many PRs each crew member has waiting.

See the review load across your team.

When to Use

• Team standup: “Who has the most reviews?”
• Load balancing: “Can someone help?”

Synopsis

prctrl team-summary [OPTIONS]

Options

Note: The global --pr flag (-p) also works with this command for consistency with other commands.

Examples

# Human-readable output
prctrl team-summary

# JSON output for scripting
prctrl team-summary --json

# Team summary for a specific repo
prctrl team-summary --repo frontend

# Team summary filtered by author
prctrl team-summary --author alice

# Team summary with priority breakdown
prctrl team-summary --priority

# Team summary for a specific PR
prctrl team-summary 4821
prctrl team-summary --pr 4821

# Team summary for PRs created in the last 7 days only
prctrl team-summary --since-days 7

Sample JSON Output

{
  "total_pending": 12,
  "by_author": {
    "alice": 5,
    "bob": 4,
    "charlie": 3
  },
  "unassigned": 0,
  "by_repository": {
    "myorg/api": 8,
    "myorg/web": 4
  }
}

load

Show review workload distribution across team members.

Analyzes how review requests are distributed across your team, identifying who is overloaded and who has capacity. Helps team leads balance review load and make informed delegation decisions.

When to Use

• Sprint planning: understand who can take on more reviews
• Identify bottlenecks: find team members with too many pending PRs
• Balance workload: redistribute reviews before standup
• Health checks: ensure no one is overwhelmed

Synopsis

prctrl load [OPTIONS]

Options

Note: The global --pr flag (-p) also works with this command for consistency with other commands.

Examples

# Show workload distribution with default threshold (3 PRs)
prctrl load

# Set custom overload threshold (5 PRs)
prctrl load --threshold 5

# Filter to a specific repository
prctrl load --repo myservice

# Filter to a specific author
prctrl load --author sarah_dev

# Only show recent PRs (last 7 days) to focus on fresh requests
prctrl load --since-days 7

# Combine filters
prctrl load --repo myservice --author sarah_dev --threshold 4

# Show priority breakdown to identify urgent PRs
prctrl load --priority

# JSON output for automation/dashboards
prctrl load --json

Output

⚖️  Review Load Distribution
──────────────────────────────────────────────────
  Total pending PRs: 24 | Team members: 8 | Overload threshold: 3 PRs

  Workload bar (max 6 PRs):
  ████████████████                                  🟢 3  
  ████████████████████████████              🟢 6  
  ████████████████████████████████  🟢 7  

  Author                     PRs     +add      -del    Avg Age    Status
  ──────────────────────────────────────────────────────────────────────
  sarah_dev                     7     +892      -124     4d       🔴 OVERLOADED
  bob_eng                       6     +445       -89     2d       🔴 OVERLOADED
  alice_ops                     3     +120       -34     1d       🔴 OVERLOADED
  charlie_dev                   2     +234       -45     3d       🟢 OK
  dan_backend                   2     +567       -78     5d       🟢 OK
  eve_frontend                  2     +189       -23     1d       🟢 OK
  frank_dev                      1     +234       -45     2d       🟢 OK
  grace_dev                      1     +98        -12     1d       🟢 OK
  ──────────────────────────────────────────────────────────────────────
  Summary: 5 healthy | 3 overloaded

  💡 Recommendations:
  • sarah_dev has the most pending PRs (7), consider reassigning some
  • Average load: 3.0 PRs per member
  • Consider delegating to: frank_dev, grace_dev

Output Fields

Status Rules

• Overloaded 🔴: PR count >= threshold (default: 3)
• OK 🟢: PR count < threshold

Recommendations

The command provides actionable recommendations:

1. Top overloaded member: Who has the most pending PRs
2. Average load: Mean PRs per team member
3. Underloaded members: Who has capacity to take more

Tips

• Use --threshold 5 in larger teams to reduce noise
• Combine with prctrl team-summary for broader team view
• Use --json output to build team dashboards
• Run before sprint planning to balance review load
• Use --repo to focus on specific repository workload distribution
• Use --author to see load breakdown for specific team members
• Use --since-days to focus on recent PRs only (e.g., --since-days 7 for last week’s requests)

Related Commands

• team-summary — Overview of team activity
• stats — Review statistics
• filter — Filter by author, repo, size
• assign — Reassign PRs to balance load

info

Show full PR information including description, reviewers, labels, and metadata.

The info command displays comprehensive details about a PR that go beyond what diff shows — including the PR body/description, requested reviewers, teams, labels, assignees, and timestamps.

When to Use

• Read the full PR description before starting a review
• Check who else is requested for review
• See PR labels and milestone context
• Get assignees information
• Verify PR metadata before commenting or approving

Synopsis

prctrl info [OPTIONS]

Options

Examples

# Show info for a specific PR
prctrl info --pr 4821

# Show info with priority score
prctrl info --pr 4821 --priority

# Show info for multiple PRs at once (fetched in parallel)
prctrl info --pr-numbers 4821,4822,4823

# Show info for all pending reviews (no interactive selection)
prctrl info --all

# Interactive mode (select from pending reviews)
prctrl info

# Filter by repository
prctrl info --repo frontend

# Filter by author
prctrl info --author sarah_dev

# Filter by both repo and author
prctrl info --repo myorg --author sarah_dev

# Show info for recent PRs (last 7 days)
prctrl info --since-days 7

# Combine filters
prctrl info --repo frontend --since-days 14 --priority

# JSON output for integration
prctrl info --pr 4821 --json

Output

When run normally, info shows:

• Header: PR number and title
• Author & Timestamps: Who opened it, when, and last update time
• Branch: Source branch name
• State: DRAFT or OPEN status
• Repository: Full repo name
• Priority Score (with --priority): 1-5 stars based on age and size
• Requested Reviewers: Individual users requested
• Requested Teams: Team slugs requested
• Labels: All labels attached to the PR
• Description: Full PR body text (truncated at 50 lines)
• URL: Direct link to the PR

╔══════════════════════════════════════════════════════════╗
║ 📋 PR #4821 — feat: add CSV export                      ║
╠══════════════════════════════════════════════════════════╣
║                                                           ║
║   👤 Author:     sarah_dev                               ║
║   📅 Created:   2026-03-20 14:30 UTC                     ║
║   🔄 Updated:   2026-03-25 09:15 UTC                     ║
║   🌿 Branch:    feature/export                           ║
║   📊 State:     OPEN                                     ║
║   📁 Repository: myorg/frontend                          ║
║   ⭐ Priority:  4/5  ⭐⭐⭐⭐☆                            ║
║                                                           ║
║   👥 Requested Reviewers:                                ║
║     @reviewer1                                           ║
║     @reviewer2                                           ║
║                                                           ║
║   🏷️  Labels:                                            ║
║     • feature                                            ║
║     • exports                                            ║
║                                                           ║
║   📝 Description:                                         ║
║ ─────────────────────────────────────────────────────────║
║   This PR adds CSV export functionality to the           ║
║   dashboard. It includes:                                ║
║                                                           ║
║   - Export button in the UI                              ║
║   - Backend endpoint for CSV generation                  ║
║   - Tests for the export function                        ║
║ ─────────────────────────────────────────────────────────║
║                                                           ║
║   🔗 https://github.com/myorg/frontend/pull/4821         ║
╚══════════════════════════════════════════════════════════╝

JSON Output

When --json is specified, outputs a structured JSON object:

{
  "number": 4821,
  "title": "feat: add CSV export",
  "author": "sarah_dev",
  "body": "This PR adds CSV export...",
  "repo": "myorg/frontend",
  "url": "https://github.com/myorg/frontend/pull/4821",
  "branch": "feature/export",
  "state": "open",
  "created_at": "2026-03-20 14:30:00 UTC",
  "updated_at": "2026-03-25 09:15:00 UTC",
  "additions": 245,
  "deletions": 32,
  "requested_reviewers": ["reviewer1", "reviewer2"],
  "requested_teams": ["team-slug"],
  "labels": ["feature", "exports"],
  "assignees": [],
  "priority_score": 4
}

Comparison with diff

Tips

• Use --json for integration with scripts or other tools
• The description is truncated at 50 lines for terminal display, but full body is shown in JSON
• Pair with claim to assign yourself and then info to read the full context

timeline

Show the chronological timeline of events on a PR (reviews, comments, labels, CI, etc.).

The timeline command displays a chronological history of all events on a PR — who requested reviews, when reviews were submitted, comments added, labels changed, branch updates, and more. It’s like a “git log” for the PR’s lifecycle.

When to Use

• Understand the full history of a PR before diving into review
• See when and why review requests were made
• Track down who made specific comments or requested changes
• Identify bottlenecks in the PR review process
• See if a PR has been sitting idle or has active discussion

Synopsis

prctrl timeline [OPTIONS]

Options

Examples

# Show timeline for a specific PR
prctrl timeline --pr 4821

# Show timelines for multiple PRs at once (fetched in parallel)
prctrl timeline --pr-numbers 4821,4822,4823

# Show timeline for all pending reviews (no interactive selection)
prctrl timeline --all

# Preview which PRs would be shown (dry run)
prctrl timeline --all --dry-run

# Interactive mode (select from pending reviews)
prctrl timeline

# JSON output for integration
prctrl timeline --pr 4821 --json

# Filter to a specific repo
prctrl timeline --repo frontend

# Filter to a specific author
prctrl timeline --author sarah_dev

# Combine filters
prctrl timeline --repo myorg --author reviewer1

# Show with priority scores to identify urgent PRs
prctrl timeline --priority

# Show timelines for recent PRs only (last 7 days)
prctrl timeline --since-days 7

# Combine filters
prctrl timeline --repo myorg --author reviewer1 --since-days 14

Output

════════════════════════════════════════════════════════════
📜 PR #4821 — feat: add CSV export Timeline
════════════════════════════════════════════════════════════

  📊 Summary: 3 reviews, 7 comments, 2 label changes, 3 other events
  ────────────────────────────────────────────────────────────

  2026-03-15 09:30  📣  PR marked as ready for review by @sarah_dev

  2026-03-15 09:31  👥  Review requested from @reviewer1

  2026-03-15 09:31  👥  Review requested from @reviewer2

  2026-03-15 14:20  💬  Comment by @reviewer1: "Looking good overall..."

  2026-03-16 10:15  🔁  CHANGES_REQUESTED by @reviewer1 review: "Please fix the..."

  2026-03-17 11:00  🏷️  Labeled with *needs-changes* by @reviewer1

  2026-03-18 16:30  💬  Comment by @sarah_dev: "Fixed! PTAL"

  2026-03-19 09:00  ✅  APPROVED by @reviewer1 review: "LGTM now"

  2026-03-19 09:05  ✅  APPROVED by @reviewer2 review

  ────────────────────────────────────────────────────────────
  🔗 https://github.com/myorg/frontend/pull/4821
════════════════════════════════════════════════════════════

Event Types

The timeline captures various event types:

JSON Output

When --json is specified, outputs a structured JSON array of events:

{
  "pr_number": 4821,
  "pr_title": "feat: add CSV export",
  "repo": "myorg/frontend",
  "url": "https://github.com/myorg/frontend/pull/4821",
  "priority_score": 4,
  "events": [
    {
      "event": "PullRequestReview",
      "created_at": "2026-03-19T09:00:00Z",
      "actor": "reviewer1",
      "data": {
        "review_state": "APPROVED",
        "body_preview": "LGTM now"
      }
    },
    ...
  ]
}

Tips

• Use --json for integration with scripts, dashboards, or custom tooling
• Timeline shows events chronologically (oldest first)
• Summary shows counts of reviews, comments, and label changes
• Great for understanding why a PR has been sitting — check the timeline to see if it’s actively being worked on or abandoned

Related Commands

• info — Show full PR details (description, labels, reviewers)
• activity — Show your recent review activity across all PRs
• chase — Send follow-up reminders to stale PR authors

assign

Assign yourself as a reviewer on a PR.

Skip the web UI — claim review responsibility directly from the terminal.

When to Use

• Quick claim: “I want to review this before anyone else”
• Triage workflow: Pair with delegate for AI-assisted assignment
• Scripting: Use --json for programmatic integrations
• Batch operation: Use --all to assign to all pending reviews at once

Synopsis

prctrl assign [OPTIONS] [PR_NUMBER]

Options

Examples

# Assign to a specific PR
prctrl assign 4821

# Preview what would be assigned (dry-run)
prctrl assign --all --dry-run

# Assign using global --pr flag
prctrl --pr 4821 assign

# Assign to all pending reviews at once
prctrl assign --all

# Assign to multiple specific PRs
prctrl assign --pr-numbers 4821,4822,4823

# Assign with JSON output (for scripting)
prctrl assign 4821 --json

# Assign to all PRs created in the last 3 days
prctrl assign --all --since-days 3

# Assign with priority scores shown (to pick highest priority PRs)
prctrl assign --priority

JSON Output

When --json is used, returns an array of results:

[
  {
    "pr_number": 4821,
    "pr_title": "Add user authentication",
    "repo": "myorg/myrepo",
    "url": "https://github.com/myorg/myrepo/pull/4821",
    "success": true,
    "error": null
  }
]

Tips

• Use --all to quickly assign yourself to ALL pending reviews without prompting
• Use --pr-numbers to assign to multiple specific PRs in one command
• Use --dry-run to preview what would be assigned before making changes
• Parallel requests are used when assigning to multiple PRs for speed

unassign

Remove yourself as a reviewer from a PR.

The counterpart to assign — give up review responsibility when you’ve been assigned by mistake or the author should have asked someone else.

When to Use

• Wrong assignment: “I was asked to review this by accident”
• Capacity shift: “I’m too busy, someone else should take this”
• Triage cleanup: Clean up your review queue after re-organizing
• Batch operation: Use --all to unassign from all pending reviews at once
• Scripting: Use --json for programmatic integrations

Synopsis

prctrl unassign [OPTIONS] [PR_NUMBER]

Options

Examples

# Unassign from a specific PR
prctrl unassign 4821

# Preview what would be unassigned (dry-run)
prctrl unassign --all --dry-run

# Unassign from all pending reviews at once
prctrl unassign --all

# Unassign from multiple specific PRs
prctrl unassign --pr-numbers 4821,4822,4823

# Interactive selection from pending reviews
prctrl unassign

# Unassign with JSON output (for scripting)
prctrl unassign 4821 --json

# Unassign from all PRs created in the last 3 days
prctrl unassign --all --since-days 3

# Unassign with priority scores shown
prctrl unassign --priority

Tips

• Use --all to quickly unassign yourself from ALL pending reviews without prompting
• Use --pr-numbers to unassign from multiple specific PRs in one command
• Use --dry-run to preview what would be unassigned before making changes
• Parallel requests are used when unassigning from multiple PRs for speed
• If no PR number is provided and --all is not used, shows your pending reviews and lets you select interactively

JSON Output

When --json is used, returns an array of results:

[
  {
    "pr_number": 4821,
    "pr_title": "Add user authentication",
    "repo": "myorg/myrepo",
    "url": "https://github.com/myorg/myrepo/pull/4821",
    "success": true,
    "error": null
  }
]

approve

Approve a PR directly from the terminal.

No more switching to GitHub UI for simple approvals. Approve and add a comment in one command.

When to Use

• Code looks good after review
• Small PR you trust the author on
• Quick approval to unblock CI
• Batch approval: Use --all to approve all pending reviews at once

Synopsis

prctrl approve [OPTIONS]

Options

Examples

# Approve a specific PR with default message
prctrl approve --pr 4821

# Approve with a custom comment
prctrl approve --pr 4821 -m "LGTM! Nice work on the tests."

# Approve without comment
prctrl approve --pr 4821 -m ""

# Preview what would be approved (dry-run)
prctrl approve --pr 4821 -n

# Preview what would be approved for all pending
prctrl approve --all -n

# Approve all pending reviews at once
prctrl approve --all

# Approve all PRs from a specific author
prctrl approve --all --author johndoe

# Approve all PRs from a specific repository
prctrl approve --all --repo myservice

# Approve PRs from the last 3 days only
prctrl approve --all --since-days 3

# Approve with priority scores shown
prctrl approve --all --priority

# Approve multiple specific PRs
prctrl approve --pr-numbers 4821,4822,4823

# Approve with JSON output (for scripting)
prctrl approve --pr 4821 --json

Tips

• Use --dry-run (-n) to preview what would be approved before actually approving
• When --pr matches a PR in multiple repos, you’ll be asked to choose which one
• Confirmation is required before approving (unless using --dry-run)

Disambiguation

If your organization has the same PR number across different repositories, using --pr will show a selection menu:

📋 PR #4821 found in multiple repos:

  1. frontend / #4821 feat: add dark mode
  2. backend / #4821 fix: login timeout

Select repo (q to quit):

This prevents accidentally approving the wrong PR.

• Use --all to quickly approve ALL pending reviews at once
• Use --author and --repo filters to narrow down which reviews to approve
• Use --priority to see priority scores when selecting reviews interactively
• Use --pr-numbers to approve multiple specific PRs in one command
• Parallel requests are used when approving multiple PRs for speed
• If no PR number is provided and --all is not used, shows your pending reviews and lets you select interactively
• Requires PR to already be reviewed (or at least have the PR in a reviewable state)

claim

Claim multiple PRs for review at once.

Sign up for review responsibility without clicking through the web UI.

When to Use

• Sprint start: “I’ll take these three”
• Batch workflow: “Claim, review, repeat”

Synopsis

prctrl claim [OPTIONS] [PR_NUMBERS]

Options

Examples

# Claim specific PRs by number
prctrl claim 4821,3156,2890

# Claim all pending reviews
prctrl claim --all

# Preview what would be claimed (dry-run)
prctrl claim --all --dry-run

# Claim all PRs from a specific repo
prctrl claim --all --repo myservice

# Claim all PRs from a specific author with priority scores
prctrl claim --all --author johndoe --priority

# Claim all PRs from the last 7 days only
prctrl claim --all --since-days 7

# Claim with JSON output for scripting
prctrl claim --all --json

comment

Post a comment on a PR directly from the CLI.

Share feedback, ask questions, or leave notes — all without leaving your terminal.

When to Use

• Leave feedback: “Minor nit, consider fixing”
• Ask questions: “Can you explain this?”
• Document decisions: “Approved with this note”
• Batch comment: Use --all to post the same comment to all pending reviews

Synopsis

prctrl comment [OPTIONS] [PR_NUMBER]

Options

Examples

# Comment on a specific PR
prctrl comment 4821 --text "Looks good, just a few nits"

# Preview what would be commented (dry-run)
prctrl comment --all --text "Please address feedback" --dry-run

# Comment on all pending reviews at once
prctrl comment --all --text "Please address feedback before merging"

# Comment on multiple specific PRs
prctrl comment --pr-numbers 4821,4822 --text "LGTM!"

# Comment on recent PRs only (last 7 days)
prctrl comment --all --since-days 7 --text "Great work!"

# Comment with priority scores shown (to pick which PRs to comment on)
prctrl comment --priority --text "Please review"

Tips

• Use --all to quickly post the same comment to ALL pending reviews at once
• Use --pr-numbers to comment on multiple specific PRs in one command
• Use --dry-run to preview what would be commented before posting
• Parallel requests are used when commenting on multiple PRs for speed
• If no PR number is provided and --all is not used, shows your pending reviews and lets you select interactively

review

Fetch and display a PR diff in the terminal with syntax highlighting.

Full code review in your terminal — no browser needed.

When to Use

• Deep dive: “I need to see the actual code”
• Offline review: “No browser, but need to review”

Synopsis

prctrl review [OPTIONS] [PR_NUMBER]

Options

Examples

prctrl review 4821
prctrl review 4821 --context 5
prctrl review --priority 4821
prctrl review 4821 --json
prctrl review --pr 4821 --output diff.patch
prctrl review --all
prctrl review --all --priority
prctrl review --all --repo myservice
prctrl review --all --author johndoe
prctrl review --all --repo api --author alice
prctrl review --pr-numbers 4821,4822,4823
prctrl review --pr-numbers 4821,4822 --priority
prctrl review --all --dry-run
prctrl review --pr 4821 --dry-run
prctrl review --all --since-days 7
prctrl review --all --repo api --since-days 14

chase

Send follow-up reminders to authors of stale PRs to get their attention.

Nothing kills momentum faster than PRs that languish without review. chase helps you send gentle, polite reminders to authors whose PRs have been waiting too long — either as a preview (default) or actually sent to GitHub.

When to Use

• Weekly maintenance: “Time to shake the trees a bit”
• Sprint end: “Let’s close out those pending reviews”
• Post-vacation: “Get eyes back on neglected PRs”
• Custom follow-up: With your own message template

Synopsis

prctrl chase [OPTIONS]

Options

Message Template

The default message is:

👋 Hi @{author}! Just checking in on this PR — it's been waiting for 
review for {days} days. Could you please address any pending feedback 
or let us know if it's ready for another look? Thanks!

Template Variables

Your custom message can include these placeholders:

Examples

# Preview chase comments for PRs older than 7 days (default behavior)
prctrl chase

# Explicitly preview what would be sent
prctrl chase --dry-run

# Chase a specific PR (ignores --min-age, targets only that PR)
prctrl chase --pr 123

# Chase multiple specific PRs by number
prctrl chase --pr-numbers 123,456,789

# Chase PRs older than 14 days and post comments
prctrl chase --min-age 14 --send

# Chase only PRs created in the last 3 days (newer stale PRs)
prctrl chase --since-days 3

# Chase PRs between 3-14 days old
prctrl chase --since-days 14 --min-age 3

# Chase with priority scores to identify most urgent PRs
prctrl chase --priority

# Use a custom message template
prctrl chase --message "Hey {author}, bumping this - it's been {days} days!"

# Get JSON output for scripting
prctrl chase --json

# Chase PRs silently (summary only, useful in scripts)
prctrl chase --send --quiet

Output

When run in preview mode (without --send):

• Shows each stale PR with author, age, and proposed comment
• Color-coded age badges (red for 14+ days, yellow for 7+ days)
• Priority scores (when --priority is specified)
• Summary of how many PRs would be chased

When run with --send:

• Posts the comment to each PR on GitHub
• Shows success/failure for each
• Final count of sent vs. failed

Safety

Dry-run by default: Without any flag, the command shows a preview. Use --dry-run to be explicit, or --send to actually post comments to GitHub.

PRs you already commented on are skipped: If you’ve already left a comment on a PR, it will be automatically skipped to avoid duplicate notifications.

Tips

• Start with a dry run to review the message tone
• Use --min-age 14 for weekly maintenance routines
• Custom messages are great for team-specific workflows
• Combine with catchup for a comprehensive review maintenance session

search

Search pending reviews by title keyword, optionally filtered by repo or author.

Find specific PRs without scrolling through the full list.

When to Use

• Remembering: “Was there a PR about auth?”
• Filtering: “Find all security-related PRs from a specific author”

Synopsis

prctrl search [OPTIONS] [PR_NUMBER] <KEYWORD>

Options

Examples

# Basic search (sorted by priority by default)
prctrl search auth

# Search within a specific repo
prctrl search auth --repo myservice

# Search for recent PRs only (last 7 days)
prctrl search auth --since-days 7

# Search for a PR by a specific author
prctrl search feature --author johndoe

# Sort by age (oldest first) instead of priority
prctrl search fix --sort-by age

# Sort by size (largest first)
prctrl search refactor --sort-by size

# Sort alphabetically by title
prctrl search update --sort-by title

# Combine filters with priority display
prctrl search fix --repo api --author alice --priority

# Target a specific PR (positional or --pr flag)
prctrl search anything 1234
prctrl search anything --pr 1234

# JSON output for scripting
prctrl search auth --json

filter

Filter PRs by multiple criteria: repository, author, size, age, or specific PR number.

Powerful way to slice through your pending reviews and find exactly what you’re looking for.

When to Use

• “Show me large PRs in the frontend repo”
• “What old PRs from alice are still waiting?”
• Building scripts that act on specific PRs
• Batch lookup of multiple specific PRs

Synopsis

prctrl filter [OPTIONS]

Options

Note: You can also use the global --pr <NUMBER> flag to target a specific PR.

Examples

# Filter to specific PR (via positional arg)
prctrl filter 123

# Filter to specific PR (via --pr flag)
prctrl filter --pr 123

# All frontend PRs
prctrl filter --repo frontend

# Big PRs only (over 500 lines)
prctrl filter --min-size 500

# Small, quick PRs (under 50 lines)
prctrl filter --max-size 50

# Old PRs that need attention
prctrl filter --min-age 7 --priority

# Combine filters: old, large, non-draft PRs from backend
prctrl filter --repo backend --min-age 3 --min-size 200 --no-drafts

# Find PRs by a specific author
prctrl filter --author alice

# Recent PRs only (last 7 days)
prctrl filter --since-days 7

# Combine filters: recent, large, non-draft PRs from backend
prctrl filter --repo backend --since-days 7 --min-size 200 --no-drafts

# Batch lookup multiple PRs (parallel fetch)
prctrl filter --pr-numbers 123,456,789

# Batch lookup with priority scores
prctrl filter --pr-numbers 123,456,789 --priority

# JSON for scripting
prctrl filter --repo api --min-size 100 --json | jq '.[].pr_number'

# Batch lookup and get JSON for scripting
prctrl filter --pr-numbers 123,456,789 --json | jq '.[].url'

# Show all large PRs without interactive selection
prctrl filter --min-size 500 --all

# Find old PRs from a specific author and show all at once
prctrl filter --author alice --min-age 7 --all --priority

Tips

• All filters are ANDed together (PR number AND repo AND author AND size…)
• Partial match on repo/author names (case-insensitive)
• Snoozed PRs are automatically hidden (use --pr to bypass snooze filter)
• When using --pr-numbers, other filters are bypassed and PRs are fetched directly in parallel
• Use --all flag to skip interactive selection and show all filtered results at once
• Great for building automation scripts

top

Show your highest priority pending PRs — sorted by age, size, and urgency.

The PRs that need your attention most.

When to Use

• Priority planning: “What matters most?”
• Neglect check: “What have I been ignoring?”

Synopsis

prctrl top [OPTIONS]

Options

Examples

# Show top 10 priority PRs
prctrl top

# Show top 5 priority PRs
prctrl top --limit 5

# Show only critical PRs (score >= 4)
prctrl top --min-score 4

# Show top PRs from a specific repo
prctrl top --repo my-service

# Show top PRs from a specific author
prctrl top --author johndoe

# Combine filters
prctrl top --repo my-service --author johndoe --min-score 4

# Show priority stars alongside scores
prctrl top --priority

# Show top PRs from the last 7 days only
prctrl top --since-days 7

# Show top PRs from the last 14 days in a specific repo
prctrl top --since-days 14 --repo my-service

Notes

• Snoozed PRs are automatically excluded from results (consistent with list, delegate, search, etc.)
• Use prctrl snooze add to temporarily hide PRs from results

Related Commands

• attention — Multi-factor urgency analysis
• focus — Show the single most urgent PR
• summary — Quick one-line overview
• snooze — Temporarily hide PRs from results

focus

Show the ONE PR you should focus on right now — the most urgent by priority score.

When you’re overwhelmed by pending reviews, focus cuts through the noise and tells you exactly which PR deserves your attention first. It calculates a priority score combining age, size, and urgency, then shows you the single most critical PR.

When to Use

• “I have 15 minutes — what should I review?”
• Starting your day and want to know where to begin
• After returning from a meeting and need a quick mental reset
• When the list feels overwhelming and you need one clear target

Synopsis

prctrl focus [OPTIONS]

Options

Examples

# See your most urgent PR right now
prctrl focus

# Preview which PR would be selected (without opening)
prctrl focus --dry-run

# See your top 3 most urgent PRs
prctrl focus --all --limit 3

# Open it directly in your browser
prctrl focus --open

# Get full details as JSON for scripting
prctrl focus --json

# See all high-priority PRs from a specific repository
prctrl focus --all --repo myservice

# Focus on PRs from a specific author
prctrl focus --author johndoe

# Show priority scores with stars
prctrl focus --priority

# Focus only on recently created PRs (last 7 days)
review-dispatcher focus --since-days 7

# Target a specific PR (bypasses priority sorting)
review-dispatcher focus --pr 4821

# Focus on multiple specific PRs
review-dispatcher focus --pr-numbers 4821,4822,4823 --all

Priority Calculation

The focused PR is selected based on a score calculated from:

Output

When run normally, focus shows:

• PR title and number
• Repository
• Author
• Age (days since created)
• Size (total lines changed)
• Priority score (1-5 stars, if --priority is set)
• Direct link to the PR

When run with --open, it opens the PR directly in your default browser.

Snooze Behavior

Snoozed PRs are automatically excluded from focus results (consistent with list, delegate, top, search, etc.). Use prctrl snooze add to temporarily hide PRs from consideration.

Tips

• Pair with claim to assign yourself to the focused PR immediately
• Use --open to jump straight into reviewing without copy-pasting URLs
• Use --repo and --author filters to narrow down which PRs to consider
• If you have no pending reviews, you’ll see an encouraging “You’re all clear!” message
• Use snooze to temporarily hide PRs from results when you need a break from certain reviews

quick

Show “quick win” PRs — small, non-draft PRs you can review in 5 minutes.

Find low-effort reviews that make a big impact.

When to Use

• Short break: “Got 5 minutes, review something”
• Review streak: “Keep momentum going”

Synopsis

prctrl quick [OPTIONS]

Options

Examples

# Show quick wins (default: ≤200 lines, non-draft)
prctrl quick

# Show tiny PRs only (≤100 lines)
prctrl quick --max-lines 100

# Show quick wins from a specific repo
prctrl quick --repo myservice

# Show quick wins with priority scores
prctrl quick --priority

# Only show recent quick wins (last 7 days)
prctrl quick --since-days 7

# Combine filters
prctrl quick --repo api --author johndoe --priority --since-days 14

catchup

Show PRs you should catch up on — oldest, longest-ignored, sorted by neglect.

Perfect for after vacation or when returning to a busy sprint.

When to Use

• Back from vacation: “What did I miss?”
• Weekly review: “What have I been neglecting?”

Synopsis

prctrl catchup [OPTIONS]

Options

Examples

# Show PRs older than 3 days
prctrl catchup

# Focus on week-old+ PRs
prctrl catchup --min-age 7

# Show priority scores for each PR
prctrl catchup --priority

# Show only PRs created in the last 14 days but older than 3 days
prctrl catchup --since-days 14 --min-age 3

# Combine with limit for more results
prctrl catchup --min-age 7 --limit 20

# Filter by repository
prctrl catchup --repo myservice

# Filter by author
prctrl catchup --author johndoe

# Show ALL neglected PRs without truncation
prctrl catchup --all

# Combine filters for targeted catchup
prctrl catchup --min-age 7 --repo api --author johndoe --priority

# Target a specific PR (bypasses --min-age filter)
prctrl catchup --pr 123
prctrl catchup 123

age

Categorize pending PRs by age — new, aging, stale, or overdue.

Visual buckets help you spot neglected PRs at a glance.

When to Use

• Morning overview: “What’s new vs. what’s been waiting?”
• Sprint planning: “What might become overdue?”

Age Buckets

Synopsis

prctrl age [OPTIONS]

Options

Examples

# Basic age overview
prctrl age

# Grouped view by bucket
prctrl age --grouped

# Show priority scores
prctrl age --priority

# Focus on older PRs
prctrl age --older-than 7
prctrl age --older-than 14 --grouped

# Filter by repo or author
prctrl age --repo myservice
prctrl age --author john

size

Categorize pending PRs by size — XS, S, M, L, XL.

Estimate review effort before you start.

Size Buckets

Synopsis

prctrl size [OPTIONS]

Options

Examples

# Show all PRs by size
prctrl size

# Group by size bucket with headers
prctrl size --grouped

# Show only small and medium PRs
prctrl size --filter-size S,M

# Show XS PRs with priority scores
prctrl size --filter-size XS --priority

# Filter by repository
prctrl size --repo myservice

# Filter by author
prctrl size --author johndoe

# Show only recent PRs (last 7 days)
prctrl size --since-days 7

# JSON output for scripting
prctrl size --json

compare

Compare two PRs side-by-side to help decide which to review first.

When you have multiple PRs competing for attention, compare gives you a head-to-head comparison based on age, size, complexity, and priority score.

When to Use

• “Should I review #123 or #456 first?”
• Sprint planning: prioritize based on urgency and effort
• Code review load balancing: understand which PR is “cheaper” to review

Synopsis

prctrl compare <PR1> <PR2> [OPTIONS]

Options

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

# Compare two PRs in the same repo
prctrl compare 123 456

# Compare PRs across different repos
prctrl compare frontend#4821 backend#1024

# Detailed comparison with language breakdown
prctrl compare 123 456 --detailed

# Show priority scores with stars
prctrl compare 123 456 --priority

# JSON output for automation
prctrl compare 123 456 --json

Output

⚖️  PR Comparison
════════════════════════════════════════════════════════════

              #123                    #456
  ──────────────────────────────────────────────────────────
  Author       alice                  bob
  Age          5 days                 2 days
  Size         +340/-25               +1200/-200
  Files        12                     8
  Draft        No                     Yes
  Priority     4/5 ⭐⭐⭐⭐           3/5 ⭐⭐⭐

  ──────────────────────────────────────────────────────────
  📊 Summary:
    • Age: #456 wins → (newer)
    • Size: #123 wins → (smaller)
    • Priority: #123 wins → (higher score)

  💻 Languages:
    PR #123: TypeScript (8), JSON (3), Markdown (1)
    PR #456: Go (5), YAML (2), Shell (1)

  🔗 Links:
    PR #123: https://github.com/myorg/frontend/pull/123
    PR #456: https://github.com/myorg/backend/pull/456

Comparison Factors

Tips

• Use prctrl top to find your highest-priority PRs first
• Combine with browse to open compared PRs directly
• For complex decisions, use --detailed to see language breakdown
• Use --priority to quickly see urgency scores as visual stars
• Consider draft PRs lower priority (they’re still in progress)

Related Commands

• top — Show highest priority PRs
• focus — Show the single most urgent PR
• summary — Quick one-line overview

stack

Detect and visualize stacked PRs (sequential dependencies).

When to Use

• Review planning: “Which PRs depend on each other?”
• Merge ordering: “What needs to merge first?”

Synopsis

prctrl stack [flags]

Detection Methods

PRCtrl uses two methods to detect stacked PRs:

1. Branch chaining — A PR’s base branch is another PR’s head branch:

• PR A: feature → main
• PR B: feature-2 → feature
• This creates a stack: PR A → PR B

2. Convention — PRs sharing the same ticket key with [N/M] position markers:

• PR #1: refactor(TAHC-1666): add client [1/3] on branch TAHC-1666-client
• PR #2: refactor(TAHC-1666): add service [2/3] on branch TAHC-1666-service
• PR #3: refactor(TAHC-1666): add tests [3/3] on branch TAHC-1666-tests
• These are grouped into a stack by the TAHC-1666 ticket key

Flags

• --json — Output as JSON (useful for scripting)
• -r, --repo <REPO> — Filter by repository name (partial match, case-insensitive)
• --author <AUTHOR> — Filter by author username
• -n, --limit <N> — Limit number of stacks to show

Examples

# Show all stacked PRs across configured repos
prctrl stack

# Filter by repository
prctrl stack --repo health-content

# Filter by author
prctrl stack --author JeremySomsouk

# Get JSON output for scripting
prctrl stack --json

# Limit to 5 stacks
prctrl stack -n 5

See Also

• mine — Shows your own PRs with automatic stack detection
• list — Use --show-stacks to display stacks with pending reviews

monitor

Watch for new PRs and get notified — runs in the background.

Perfect for developers who want to know immediately when their attention is needed, without constantly checking manually.

When to Use

• You want instant notifications for new PRs
• You’re in a flow state and don’t want to switch contexts
• You need to catch PRs that request your review ASAP

Synopsis

prctrl monitor [OPTIONS]

Options

Note: --notify and --auto-open are disabled by default. Use --notify to enable notifications, and --auto-open (or --notify --auto-open) to also open PRs automatically.

Examples

# Start monitoring with defaults (checks every 5 minutes, no notifications)
prctrl monitor

# Check more frequently (every minute)
prctrl monitor --interval 60

# Enable notifications (no auto-open)
prctrl monitor --notify

# Enable notifications AND auto-open in Chrome
prctrl monitor --notify --auto-open

# Notifications only, no auto-open (good for meetings)
prctrl monitor --notify --no-auto-open

# Interactive mode - choose what to do for each new PR
prctrl monitor --notify --interactive

# Run in background (add & to detach)
prctrl monitor &

Interactive Mode Actions

When --interactive is enabled, each new PR shows:

🔔 New PR: feat: add dark mode #4821

🎯 What to do?
  [d] Delegate to Claude
  [o] Open in browser
  [a] Assign myself
  [s] Snooze (hide for 3 days)
  [q] Quit monitoring

Background Operation

# Start and detach
prctrl monitor &

# Check if running
prctrl monitor-status

# Stop monitoring
prctrl monitor-stop

Tips

• Use --interval 60 during code freeze/release when PRs pile up
• Combine with --no-auto-open when you need to context-switch carefully
• The monitor process survives terminal restarts (uses a PID file)

monitor-stop

Stop the running monitor process.

Gracefully stop background monitoring.

Synopsis

prctrl monitor-stop

monitor-status

Check if monitor process is running.

See whether background monitoring is active.

Synopsis

prctrl monitor-status

ping

Send emoji reactions to PR authors to get their attention without leaving a comment.

A lightweight, non-intrusive way to nudge authors — the equivalent of tapping someone’s shoulder in a hallway. GitHub shows reactions inline on the PR, so authors notice them immediately without your reaction cluttering the comment thread.

When to Use

• PR has been waiting for review and you want a gentle reminder
• You want to acknowledge a PR without doing a full review yet
• Following up on a previously reviewed PR
• When chase feels too formal but you want to do something

Synopsis

prctrl ping [OPTIONS]

Options

Available Emojis

How It Works

The ping command uses GitHub’s emoji reactions API:

1. Preview mode (default) — shows what would be sent without actually reacting
2. Send mode (--send) — actually posts the emoji reaction to the PR

Unlike comments, reactions:

• Don’t generate notification spam for the author
• Are visible immediately in the PR’s reaction summary
• Can be added by anyone, not just reviewers

Output

Preview mode:

👀 Ping Command
──────────────────────────────────────────────────
  Emoji: eyes

  🔍 Will ping #4821 — Fix authentication bug by @alice (3 days old)

──────────────────────────────────────────────────
  💡 Use `--send` to actually send the emoji reactions
  💡 Available emojis: eyes (default), rocket, heart, +1, hooray
  💡 Use `-e rocket` or `-e heart` to change emoji

Dry-run mode:

👀 Ping Command
────────────────────────────────────────────────--
  Emoji: eyes

  🔍 Dry-run: would ping #4821 — Fix authentication bug by @alice (3 days old)

────────────────────────────────────────────────--
  (dry-run — no emoji reactions sent)

JSON output:

[
  {
    "repo": "my-service",
    "pr_number": 4821,
    "pr_title": "Fix authentication bug",
    "pr_author": "alice",
    "pr_url": "https://github.com/org/my-service/pull/4821",
    "age_days": 3,
    "emoji": "eyes"
  }
]

Send mode:

👀 Ping Command
──────────────────────────────────────────────────
  Emoji: eyes

  📤 Sending #4821 — Fix authentication bug by @alice (3 days old)
  📤 Sending #4822 — Update dependencies by @bob (1 days old)

⏳ Sending 2 emoji reaction(s) in parallel...

  ✅ #4821 — Fix authentication bug
  ✅ #4822 — Update dependencies

📊 Sent: 2, Failed: 0

Examples

# Preview what would happen (default)
prctrl ping

# Preview with dry-run flag (explicit preview mode)
prctrl ping --dry-run
prctrl ping -n

# Output as JSON (useful for scripting)
prctrl ping --all --json

# Ping specific PRs (interactive selection)
prctrl ping 4821
prctrl ping 4821,4815,4809

# Send 👀 (eyes) emoji — default
prctrl ping 4821 --send

# Ping a specific PR directly with --pr flag
prctrl ping --pr 4821 --send

# Send 🚀 (rocket) for urgent follow-up
prctrl ping --emoji rocket --send

# Ping all pending reviews at once
prctrl ping --all --send

# Use thumbs up 👍 instead
prctrl ping -e +1 4821 --send

# Ping PRs from a specific repository
prctrl ping --repo my-service --all --send

# Ping PRs from a specific author
prctrl ping --author alice --all --send

# Ping PRs created in the last 3 days (newer PRs only)
prctrl ping --since-days 3 --all --send

# Combine filters for targeted pinging
prctrl ping --repo api --author bob --send

Tips

• Be mindful: Don’t spam the same PR with multiple reactions
• Pair with chase: Use ping for gentle nudges, chase for formal reminders
• Preview first: Always preview before sending (--send is explicit)
• Rocket emoji: Great for signaling a PR is ready for final review

Related Commands

• chase — Send formal comment reminders
• attention — Find PRs that need your attention
• focus — Focus on the most urgent PR

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

Options

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:

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

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

Storage

Followed PRs are stored in:

<review_output_dir>/.followed.json

Related Commands

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

diff

Show detailed diff/stats for one or more PRs directly in the terminal.

Synopsis

prctrl diff [OPTIONS]

Options

Examples

# Show diff for a specific PR (positional)
prctrl diff 4821

# Show diff for a specific PR (shorthand)
prctrl diff --pr 4821
prctrl diff -p 4821

# Show diffs for multiple PRs at once
prctrl diff --pr-numbers 4821,4822,4823

# Interactive mode (select from pending reviews)
prctrl diff

# Show diff/stats for ALL pending reviews at once
prctrl diff --all

# Preview which PRs would be diffed (without displaying)
prctrl diff --all --dry-run
prctrl diff --all -n

# Show diffs for all PRs in a specific repo
prctrl diff --all --repo frontend

# Filter to specific author before selecting
prctrl diff --author sarah_dev

# Show only recent PRs (last 7 days)
prctrl diff --all --since-days 7

# Combine filters
prctrl diff --all --repo frontend --since-days 14

# JSON output for scripting
prctrl diff --pr 4821 --json

# Show priority scores
prctrl diff --pr 4821 --priority

Output

Displays comprehensive PR information including:

• Title & Number: PR title with number
• Author & Age: Who opened it and when
• Branch: Source branch name
• Status: DRAFT or READY status
• Lines: Additions and deletions
• Size Category: XS (<50), S (50-200), M (200-500), L (500-1000), XL (1000+)
• Age Category: 🔥 HOT (today), ⚡ FRESH (1-2d), 📅 WEEK OLD (3-7d), ⚠️ STALE (8-14d), 🚨 OLD (15d+)
• Priority Score: 1-5 star rating based on urgency (only when --priority flag is used)
• Repository: Full repo name
• URL: Direct link to the PR

JSON Output

When --json is used, outputs a single JSON object per PR:

{
  "pr_number": 4821,
  "pr_title": "feat: add CSV export",
  "repo": "myorg/frontend",
  "author": "sarah_dev",
  "branch": "feature/export",
  "url": "https://github.com/myorg/frontend/pull/4821",
  "age_days": 5,
  "age_category": "WEEK_OLD",
  "size_lines": 277,
  "size_category": "M",
  "additions": 245,
  "deletions": 32,
  "draft": false,
  "priority_score": 3
}

files

Show changed files for one or more PRs.

Quickly see which files were modified before diving into the diff.

When to Use

• Pre-review scan: “What did they change?”
• Impact assessment: “Which services are affected?”

Synopsis

prctrl files [OPTIONS] [PR_NUMBER]

Options

Examples

# Show files for a specific PR
prctrl files 4821
prctrl files --pr 4821

# Show files for multiple PRs
prctrl files --pr-numbers 4821,3156,2890

# Show files for all pending reviews
prctrl files --all

# Filter by repository
prctrl files --all --repo myservice

# Filter by author
prctrl files --all --author johndoe

# Combined filters
prctrl files --all --repo api --priority

# Only show files for recent PRs (last 7 days)
prctrl files --all --since-days 7

# JSON output for scripting
prctrl files --pr 4821 --json

JSON Output

When --json is specified, output includes for each PR:

• pr_number, pr_title, repo, url
• total_files, total_additions, total_deletions
• files[] - array of file objects with filename, status, additions, deletions

Notes

• Snoozed PRs are automatically excluded when using --all or interactive selection (consistent with search, top, delegate, and list commands)
• Use --pr to bypass snooze exclusion and view files for a specific snoozed PR

ci

Show CI/CD pipeline status for pending PRs — GitHub Actions, etc.

See which PRs are green, failing, or still running.

When to Use

• Pre-review check: “Is this PR even ready?”
• CI debugging: “Why is this failing?”
• Merge planning: “Which PRs can I merge now?”

Filter Behavior

Filters (--repo, --author, --since-days) are applied before fetching CI status, reducing API calls and improving performance. When a specific PR is targeted via positional argument or --pr, filters are skipped to ensure accurate targeting.

Synopsis

prctrl ci [OPTIONS]

Options

Examples

prctrl ci
prctrl ci --failing-only
prctrl ci --passing-only
prctrl ci -f -a
prctrl ci --repo myrepo
prctrl ci --author johndoe
prctrl ci --repo myrepo --failing-only
prctrl ci --pr 123
prctrl ci 123
prctrl ci --since-days 7
prctrl ci --since-days 3 --failing-only
prctrl ci --priority
prctrl ci -f --priority

blocked

Show PRs that are blocked from merging — CI failures, merge conflicts, or other issues.

Find PRs that can’t be merged yet and see exactly what’s blocking them.

When to Use

• Merge queue planning: “What’s blocking our PRs?”
• CI debugging: “Why is this PR blocked?”
• Conflicts check: “Do we have merge conflicts to resolve?”

Synopsis

prctrl blocked [OPTIONS]

Options

Examples

# Show all blocked PRs
prctrl blocked

# Show only PRs with CI failures
prctrl blocked --ci-only

# Show only PRs with merge conflicts
prctrl blocked --conflicts-only

# Filter to specific repo
prctrl blocked --repo frontend

# Filter by author
prctrl blocked --author alice

# Show priority scores
prctrl blocked --priority

# Combine filters
prctrl blocked --repo frontend --priority --ci-only

# Only show recently created PRs (last 7 days)
prctrl blocked --since-days 7

# JSON output for scripting
prctrl blocked --json

Output Details

Each blocked PR shows:

• PR number and title: Which PR is blocked
• Blocker reasons: Why it can’t be merged (CI failing, conflicts, draft, etc.)
• Author and age: Who owns it and how long it’s been waiting
• Priority score: When --priority is used, shows urgency rating

conflicts

Show which pending PRs have merge conflicts.

Avoid wasting time on PRs that can’t be merged yet.

When to Use

• Pre-review: “Is this even mergeable?”
• Sprint planning: “Which PRs are blocked?”
• Merge day: “What can we actually ship?”

Synopsis

prctrl conflicts [OPTIONS]

Options

Examples

# Check all pending PRs for conflicts
prctrl conflicts

# Show only PRs with conflicts
prctrl conflicts --conflicts-only

# Check conflict status for specific PRs
prctrl conflicts --pr-numbers 123,456,789

# Check a specific PR
prctrl conflicts --pr 123

# Check conflict status for all pending reviews
prctrl conflicts --all

# Check conflicts for a specific repo
prctrl conflicts --repo myservice

# Check conflicts for PRs by a specific author
prctrl conflicts --author johndoe

# Show priority scores alongside conflict status
prctrl conflicts --priority

# Check conflicts for PRs created in the last 3 days
prctrl conflicts --since-days 3

labels

Show labels for one or more PRs.

Quickly see what tags and categories are applied to your pending PRs.

When to Use

• Filtering: “Find all ‘security’ PRs”
• Organization: “What labels are being used?”

Synopsis

prctrl labels [OPTIONS] [PR_NUMBER]

Options

Examples

# Show labels for a specific PR
prctrl labels 4821

# Show labels for specific PR (using --pr flag)
prctrl labels --pr 4821

# Show labels for multiple PRs
prctrl labels --pr-numbers 4821,4822,4823

# Filter labels by name containing "security"
prctrl labels -a -l security

# Filter by repository name
prctrl labels --repo api-service

# Filter by author
prctrl labels --author alice

# Show labels for all PRs from the last 7 days
prctrl labels -a --since-days 7

# Combine filters
prctrl labels -a --repo api --author alice --since-days 14

# Output as JSON for scripting
prctrl labels --pr 4821 --json

# Show priority scores alongside labels
prctrl labels -a --priority

activity

Show your recent review activity — PRs you reviewed in the last N days.

Track your review throughput and see what you’ve been up to.

When to Use

• Weekly check: “How much did I review this week?”
• Performance reviews: “Show my review history”
• Team reporting: “Here’s my review output”

Synopsis

prctrl activity [OPTIONS]

Options

Examples

# Last week's reviews
prctrl activity

# Last 30 days
prctrl activity --days 30

# Filter by repository
prctrl activity --repo myrepo

# Filter by author
prctrl activity --author johndoe

# Combine filters
prctrl activity --days 14 --repo api --author alice

# Activity for specific PR
prctrl activity --pr 123

# Show priority scores for reviewed PRs
prctrl activity --priority

# JSON output for scripting
prctrl activity --json

# Only show PRs reviewed in the last 7 days (even if --days is 30)
prctrl activity --days 30 --since-days 7

mentions

Show GitHub notifications where you were mentioned or directly involved.

Stay on top of conversations without opening GitHub.

Note: The --author filter now properly fetches and matches against the PR author’s username.

When to Use

• Morning check: “Any mentions while I was offline?”
• Follow-up: “What threads am I in?”
• Check for activity on a specific PR

Synopsis

prctrl mentions [OPTIONS]

Options

Examples

# Show all notifications
prctrl mentions

# Show only unread notifications
prctrl mentions --unread

# Check notifications for a specific PR
prctrl mentions --pr 123

# Combine with unread filter
prctrl mentions --pr 123 --unread

# Only show notifications from the last 3 days
prctrl mentions --since-days 3

# Filter by repository and time window
prctrl mentions --repo myorg --since-days 7

# Filter by author username
prctrl mentions --author johndoe

# Show priority scores for urgent notifications
prctrl mentions --priority

# Combine filters with priority
prctrl mentions --repo myorg --priority --since-days 3

# JSON output for scripting
prctrl mentions --json

summary

Show a quick one-line summary of pending reviews.

The fastest way to get an at-a-glance view of your review queue.

When to Use

• Slack check: “How backed up am I?”
• Shell prompt: “Drop it in your terminal status bar”

Synopsis

prctrl summary [OPTIONS]

Options

Examples

prctrl summary
prctrl summary --json
prctrl summary --repo myrepo
prctrl summary --author johndoe
prctrl summary --since-days 7
prctrl summary --priority

Output Example

📋 12 PRs  ⏱️ oldest: 3d  +892/-234 lines  [🔥1/⚡2/📅5/💤4]  (2 draft)
   📁 repo1: 5 • repo2: 4 • repo3: 3

  ⭐ Priority breakdown:
    ⭐⭐⭐⭐⭐  1 PR(s)  •  oldest: 5 days  •  +450/-120 lines
    ⭐⭐⭐⭐   2 PR(s)  •  oldest: 3 days  •  +200/-80 lines
    ⭐⭐⭐    5 PR(s)  •  oldest: 2 days  •  +150/-30 lines
    ⭐⭐     3 PR(s)  •  oldest: 1 day  •  +60/-15 lines
    ⭐      1 PR(s)  •  oldest: today  •  +32/-9 lines

  🚨 Most Urgent:
    Fix authentication bug  #123  ⭐⭐⭐⭐⭐
    👤 johndoe  •  📦 570 lines  •  5 old  •  myorg/myrepo
    🔗 https://github.com/myorg/myrepo/pull/123

attention

Analyze which PRs demand your immediate attention based on multiple urgency factors.

When you’re overwhelmed by pending reviews, attention cuts through the noise by calculating a multi-factor attention score for each PR. Unlike the simple priority score, it combines age, size, staleness, and draft status into a comprehensive urgency metric (1-10 scale).

When to Use

• Morning triage: “Which PRs should I prioritize today?”
• End-of-day review: “What did I miss that needs urgent attention?”
• Sprint planning: “Which PRs are becoming critical?”
• When focus is too narrow and you need a broader view of urgency

Synopsis

prctrl attention [OPTIONS]

Options

Attention Score Calculation

The attention score (1-10) combines four factors:

Score Thresholds

Examples

# See your most attention-demanding PRs
prctrl attention

# Show only critical PRs (score >= 8)
prctrl attention --threshold 8

# Show detailed breakdown of why each PR scored high
prctrl attention --detailed

# Show top 5 most urgent
prctrl attention --limit 5

# Show with priority scores (1-5 stars)
prctrl attention --priority

# Filter by repository
prctrl attention --repo myorg/frontend

# Filter by author
prctrl attention --author alice

# Only show PRs from the last 7 days
prctrl attention --since-days 7

# Combine filters
prctrl attention --repo myorg --author alice --priority

# Get JSON for scripting or dashboards
prctrl attention --json

Output

🎯 3 PR(s) demand your attention (score >= 5)

  🔥🔥🔥  Fix authentication bug  #4821  (myorg/frontend)
      👤 alice  •  340 lines  •  opened 5d
      🔗 https://github.com/myorg/frontend/pull/4821

  🔥🔥  Refactor API gateway  #4815  (myorg/backend)
      👤 bob  •  890 lines  •  opened 3d
      🔗 https://github.com/myorg/backend/pull/4815

  🔥🔥  Update dependencies  #4809  (myorg/shared)
      👤 carol  •  120 lines  •  opened 2d
      🔗 https://github.com/myorg/shared/pull/4809

With --detailed flag

  🔥🔥🔥  Fix authentication bug  #4821  (myorg/frontend)
      👤 alice  •  340 lines  •  opened 5d
      📊 breakdown: age=3 size=2 draft=2 stale_bonus=1
      🔗 https://github.com/myorg/frontend/pull/4821

Tips

• Use --threshold 8 to see only truly critical PRs
• Combine with --detailed when explaining to others why a PR is urgent
• Use --json for integration with external tools or Slack notifications
• Pair with focus --open to immediately start reviewing the most urgent PR
• Snoozed PRs are automatically excluded from results (consistent with list, delegate, etc.)
• Use prctrl snooze add to temporarily hide PRs from results

Related Commands

• focus — Show the single most urgent PR
• summary — Quick one-line overview
• top — Highest priority PRs by score
• snooze — Temporarily hide PRs from results

health

Show GitHub API health status and rate limits.

Avoid hitting rate limits by checking before large operations.

When to Use

• Before batch operations: “Will I hit the limit?”
• Debugging: “Why is the CLI slow?”
• Planning: “Which commands can I safely run right now?”

Synopsis

prctrl health [OPTIONS]

Options

Examples

# Basic health check
prctrl health

# With actionable recommendations
prctrl health --suggest
prctrl health -s

# JSON output for scripting
prctrl health --json

Output Details

Rate Limit Display

The health command shows all GitHub API rate limits with visual indicators:

• 🟢 Green: More than 50% remaining
• 🟠 Yellow: 10-50% remaining
• 🟡 Yellow: Less than 10% remaining
• 🔴 Red: Exhausted (0 remaining)

API Cost Table (–suggest)

When using --suggest, a table shows approximate API costs per command:

  📊 Command API Costs (approximate GitHub API calls):

  Command                    Calls   Notes
  ────────────────────────────────────────────────────────────────
  🟢 list                      ~1   per repo (list PRs)
  🟢 list --all                ~3   all repos + details
  🟢 delegate --dry-run        ~3   preview without CLAUDE
  🟡 delegate                  ~8   +PR details +CLAUDE API
  🔴 activity                  ~8   all repos + timelines

Color indicators show affordability based on remaining quota:

• 🟢 Green: Safe to run (remaining >= 10 calls)
• 🟡 Yellow: Use with caution (remaining >= command cost)
• 🔴 Red: Avoid until reset (remaining < command cost)

Tips

• Commands with --dry-run cost ~3x less (skip external API calls like CLAUDE)
• Batch commands (--all) multiply API costs by number of PRs
• Use --json to reduce output parsing overhead
• When rate limits are low, prefer summary over stats (fewer API calls)

Browse

Open one or more PRs in your browser.

Jump straight to GitHub without switching windows or copying URLs.

Note: Snoozed PRs are automatically excluded from results (unless you specify a specific PR with --pr or --pr-numbers). This is consistent with other commands like list and delegate.

When to Use

• After triage: “Let me see the actual code”
• Quick access: “Open all my pending PRs”

Synopsis

prctrl browse [OPTIONS] [PR_NUMBER]

Options

Note: The global --pr flag (-p) also works with this command for consistency with other commands.

Examples

# Open a specific PR in browser
prctrl browse 4821
prctrl browse --pr 4821

# Open multiple PRs in browser
prctrl browse --pr-numbers 4821,3156,2890

# Open multiple PRs from a specific repository (filters applied after fetch)
prctrl browse --pr-numbers 4821,3156,2890 --repo myservice

# Open all pending reviews at once
prctrl browse --all

# Open all pending reviews from a specific repository
prctrl browse --all --repo myservice

# Open all pending reviews from a specific author
prctrl browse --all --author johndoe

# Open all pending reviews from a repository by an author
prctrl browse --all --repo myservice --author johndoe

# Open recent PRs (last 7 days) from a repository
prctrl browse --all --repo myservice --since-days 7

# Open old PRs needing attention (more than 7 days old)
prctrl browse --all --since-days 30

# Preview which PRs would be opened (dry-run)
prctrl browse --dry-run

# Preview opening specific PRs
prctrl browse --pr-numbers 4821,3156 --dry-run

# Output URLs as JSON (useful for scripting)
prctrl browse --pr 4821 --json

# Quiet mode - open PRs with minimal output
prctrl browse --all --quiet

# Show priority scores when browsing (helps decide which PRs to open first)
prctrl browse --all --priority

# Show priority scores in JSON output for scripting
prctrl browse --all --json --priority

ready

Show PRs that are ready to merge — approved, CI passing, no conflicts.

A merge-ready PR is one that has:

• ✅ Not a draft
• ✅ CI/CD checks passing (or pending)
• ✅ No merge conflicts
• ✅ Is mergeable (GitHub says so)

When to Use

• Morning check: “Which PRs can I merge right now?”
• Release planning: “What’s blocking the merge queue?”
• Dashboard prep: “Get a quick list of deployable changes”
• QA handoff: “Verify which PRs are good to go”

Synopsis

prctrl ready [OPTIONS]

Options

How It Works

The ready command analyzes your pending review PRs and checks each one’s merge readiness:

1. Fetches CI status via GitHub’s combined status API
2. Checks merge conflicts using GitHub’s mergeable field
3. Filters out drafts (not ready for merge)
4. Sorts by age — oldest mergeable PRs first

A PR is considered “ready to merge” when:

• draft = false
• ci_status = "success" or "pending"
• mergeable = true (not false)
• has_conflicts = false

Output

🚀 Merge Readiness — 8 PRs total, 3 ready to merge
──────────────────────────────────────────────────

  ✅  #4821  Fix authentication bug
      👤 alice  •  📦 +340/-25  •  ⏱️ 2 days  •  ✅ CI
      📁 myorg/frontend  🔗 https://github.com/myorg/frontend/pull/4821

  ✅  #4815  Update dependencies
      👤 bob  •  📦 +50/-10  •  ⏱️ today  •  ✅ CI
      📁 myorg/shared  🔗 https://github.com/myorg/shared/pull/4815

  ⏳  #4809  Refactor API gateway
      👤 carol  •  📦 +1200/-200  •  ⏱️ 5 days  •  ⏳ CI pending
      📁 myorg/backend  🔗 https://github.com/myorg/backend/pull/4809

──────────────────────────────────────────────────
  💡 Ready = not draft + CI passing + no conflicts
  💡 Use `--json` for scripting

With Priority Flag

When --priority is enabled, each PR shows its priority score:

🚀 Merge Readiness — 8 PRs total, 3 ready to merge
──────────────────────────────────────────────────

  ✅  #4821  Fix authentication bug  ⭐⭐⭐⭐
      👤 alice  •  📦 +340/-25  •  ⏱️ 2 days  •  ✅ CI
      📁 myorg/frontend  🔗 https://github.com/myorg/frontend/pull/4821

  ✅  #4815  Update dependencies  ⭐
      👤 bob  •  📦 +50/-10  •  ⏱️ today  •  ✅ CI
      📁 myorg/shared  🔗 https://github.com/myorg/shared/pull/4815

──────────────────────────────────────────────────
  💡 Ready = not draft + CI passing + no conflicts
  💡 Priority based on age and size
  💡 Use `--json` for scripting

Examples

# Interactive: show all pending PRs with readiness status
prctrl ready

# Check specific PR by number
prctrl ready --pr 1234

# Check multiple PRs at once
prctrl ready --pr-numbers 1234,5678,9012

# Check all pending reviews (non-interactive)
prctrl ready --all

# Filter to specific repo
prctrl ready --repo frontend

# Filter by author
prctrl ready --author alice

# Filter by repo and author combined
prctrl ready --repo backend --author bob

# Only show PRs from the last 7 days
prctrl ready --since-days 7

# Only show PRs from today
prctrl ready --since-days 1

# Show priority scores to identify most urgent ready PRs
prctrl ready --priority

# JSON output for scripting
prctrl ready --json

# Combine with other commands
prctrl ready --repo backend | grep "✅"

Tips

• Use --json for integration with dashboards or automation scripts
• Pipe to grep "✅" to get just the ready PRs
• Ready PRs are sorted by age — oldest first
• CI “pending” is counted as ready (in progress, not failed)
• Combine with browse to quickly open merge-ready PRs

Related Commands

• ci — Detailed CI/CD pipeline status
• conflicts — Find PRs with merge conflicts
• browse — Open PRs in browser

snooze

Temporarily hide PRs from the pending list.

Snooze PRs you’re not ready to review yet.

When to Use

• Context overload: “Not now, remind me later”
• Vacation: “Hide until I return”

Synopsis

prctrl snooze [OPTIONS] [PR_NUMBER] [PR_NUMBERS]

Options

Subcommands

list

List all currently snoozed PRs.

prctrl snooze list
prctrl snooze list --repo myrepo
prctrl snooze list --author johndoe
prctrl snooze list --repo myrepo --author johndoe

review

Show detailed view of snoozed PRs with full metadata.

prctrl snooze review
prctrl snooze review --repo myrepo

add

Add PR(s) to the snooze list. When using interactive selection (no PR specified), --repo and --author filters are applied to narrow down the list of pending reviews shown.

prctrl snooze add 4821
prctrl snooze 4821 --days 7
prctrl snooze add 4821,4822,4823
prctrl snooze add --repo myservice --author johndoe

remove

Remove PR(s) from the snooze list (wake them up).

prctrl snooze remove 4821
prctrl snooze remove --pr 4821
prctrl snooze remove 4821,4822,4823

clear

Clear all snoozed PRs.

prctrl snooze clear

expire

Remove expired snooze entries.

prctrl snooze expire

extend

Extend snooze duration for already-snoozed PRs.

prctrl snooze extend 4821 --days 7
prctrl snooze extend --pr 4821 --days 7
prctrl snooze extend 4821,4822,4823 --days 5

Examples

# Snooze a single PR for 3 days (using positional argument)
prctrl snooze 4821

# Snooze a single PR using --pr flag
prctrl snooze add --pr 4821

# Snooze for 7 days
prctrl snooze 4821 --days 7

# Snooze all PRs from the last 2 weeks (interactive selection)
prctrl snooze add --since-days 14

# List snoozed PRs as JSON (for scripting)
prctrl snooze list --json

# List snoozed PRs with priority scores
prctrl snooze list --priority

# List snoozed PRs filtered by repository
prctrl snooze list --repo myrepo

# List snoozed PRs filtered by author
prctrl snooze list --author johndoe

# Show detailed view filtered by repo
prctrl snooze review --repo myrepo

snooze review

Show detailed information about your snoozed PRs — author, age, size, and priority.

When you’ve snoozed multiple PRs and want to review them in detail before waking them up, snooze review provides a richer view than snooze list. It shows the full context: who authored each PR, how many lines were changed, when you snoozed it, and the original priority score.

When to Use

• “I have 5 snoozed PRs — which one should I wake up first?”
• Before unwaking a PR, check its current priority
• Review the context of snoozed PRs without fetching fresh GitHub data
• Plan your review session by understanding what you deferred

Synopsis

prctrl snooze review

Options

This command has no additional options — it always shows the full detailed view of all currently snoozed PRs.

Examples

# View all snoozed PRs with full details
prctrl snooze review

# See which ones are coming close to expiry
prctrl snooze review

Output

snooze review shows for each snoozed PR:

Comparison with snooze list

Tips

• Use snooze review before snooze remove to remember why you snoozed something
• If a snoozed PR’s priority score was high (4-5 stars), consider prioritizing it when you wake it
• Snoozed PRs automatically expire and reappear in your pending list

See Also

• snooze list — Quick summary view
• snooze remove — Wake a PR early
• snooze extend — Extend snooze duration
• snooze expire — Remove expired entries

snooze extend

Extend the snooze duration for already-snoozed PRs.

Pick up where you left off — push a PR’s snooze further into the future without removing and re-adding it.

When to Use

• “I still can’t review this, extend it”
• Deadline approaching: “Push it back another few days”
• Recurring PRs that keep appearing and need continuous snoozing

Synopsis

prctrl snooze extend [OPTIONS] [PR_NUMBERS]

Options

Examples

# Extend a single PR by 3 days (default)
prctrl snooze extend 4821

# Extend multiple PRs by 7 days
prctrl snooze extend 4821,4519 --days 7

# Interactive: select from currently snoozed PRs
prctrl snooze extend

Output Example

✅ Extended 2 PR(s) until 2026-04-03 (7 days)

📋 Currently snoozed PRs (select to extend):

──────────────────────────────────────────────────
  [1] Fix auth token refresh  #4821 (myorg/frontend) - 2h left
  [2] Update dependencies    #4519 (myorg/backend)  - 18h left
──────────────────────────────────────────────────

 Select PRs to extend [e.g. 1,3 or 1-3 or 'all'] (q to quit): 1,2

✅ Extended 2 PR(s) until 2026-04-03 (3 days)

How It Works

1. Loads the .snoozed.json file from your output directory
2. Finds PRs that are currently snoozed
3. Updates their snoozed_until timestamp to a new time in the future
4. Saves the updated list back to .snoozed.json

Relationship to Other Commands

Tips

• Use snooze list first to see which PRs are currently snoozed and how much time remains
• If you try to extend a PR that isn’t in the snooze list, you’ll get a warning to use snooze add first
• The --days flag sets the new total duration from now, not additional time

snooze expire

Remove expired snooze entries and restore PRs to your pending list.

Automatically clean up snoozed PRs whose snooze duration has elapsed. Expired entries are permanently removed from the snooze list, making those PRs visible again in your pending reviews.

When to Use

• Routine maintenance: Run periodically to keep your snooze list clean
• After returning from vacation: Clean up old snoozes you forgot about
• As part of a daily/weekly script: Automate cleanup alongside other review tasks

Synopsis

prctrl snooze expire

Options

This subcommand has no additional flags.

Examples

# Clean up all expired snooze entries
prctrl snooze expire

# Expected output (when there are expired entries):
# 🧹 Cleaned up 3 expired snooze entry(s):
#   ✨ Fix authentication bug #456 (myorg/myrepo)
#   ✨ Update dependencies #789 (myorg/other-repo)
#   ✨ Add user dashboard #101 (myorg/myrepo)
#
#   ↩️ 3 PR(s) have returned to your pending list.
# ✅ 7 snoozed PR(s) remain in the list.

# Expected output (when nothing has expired):
# ✨ No expired snooze entries to clean up.

How It Works

1. Reads the .snoozed.json file from your output directory
2. Checks each entry’s snoozed_until timestamp against the current time
3. Removes entries where the snooze period has passed
4. Saves the updated list back to .snoozed.json
5. Reports how many entries were cleaned and how many remain

Relationship to Other Commands

Tips

• Run snooze expire before list to see all PRs including recently snoozed ones that have expired
• For automation, add snooze expire to your daily review script before fetching pending reviews
• Snoozed PRs are hidden from list but don’t automatically reappear — use expire to restore them

report

Generate a weekly review report from processed review files.

See your review activity over time — PRs reviewed, time spent, patterns.

When to Use

• Weekly summary: “What did I review this week?”
• Team reporting: “Show my review output”
• Per-PR analysis: “Show me details for a specific PR”

Synopsis

prctrl report [OPTIONS]

Options

Examples

prctrl report
prctrl report --days 30
prctrl report --repo api
prctrl report --author alice --priority
prctrl report --days 14 --repo backend --priority
prctrl report --since-days 3 --priority
prctrl report --pr 123
prctrl report --pr 123 --json
prctrl report --pr-numbers 123,456,789
prctrl report --all --priority
prctrl report --all --repo myorg --since-days 7

Tips

• Review files must exist in the output directory
• Use clean before generating a fresh report
• Use --priority to see which pending PRs are most urgent
• Use --since-days to filter pending PRs (consistent with list, stats, delegate commands)
• Use [PR_NUMBER] or --pr to target a specific PR (JSON output includes full PR details)
• Use --pr-numbers to target multiple specific PRs at once (fetches in parallel)
• Use --all to include all pending reviews in the report without prompting

review-time

Estimate how long each PR will take to review based on size and complexity.

Review time estimation helps you plan your review sessions and prioritize efficiently.

When to Use

• Morning planning: “What can I realistically review today?”
• Time-boxing: “I have 2 hours before lunch — which PRs fit?”
• Sprint planning: “Budget review time across the sprint”
• Delegation: “Which PRs can I handle vs. should delegate?”

Synopsis

prctrl review-time [OPTIONS]

Options

How It Works

The estimation algorithm considers:

1. Lines changed — Base formula: ~2 min per 50 lines
2. File count — Number of files changed (fetched in parallel for performance)
3. Size complexity — Larger PRs get a complexity multiplier:
   • XS (<50 lines): 0.8x (quick win)
   • S (50-200 lines): 1.0x (standard)
   • M (200-500 lines): 1.2x (moderate complexity)
   • L (500-1000 lines): 1.5x (higher complexity)
   • XL (1000+ lines): 2.0x (large, likely complex)
4. Age factor — PRs older than 14 days get 0.9x (context lost)
5. Minimum floor — No estimate under 5 minutes

Time Categories

Examples

# Interactive: select PRs from pending list
prctrl review-time

# Target specific PR directly (consistent with other commands)
prctrl review-time --pr 4821
prctrl review-time -p 4821

# Estimate for specific PRs via positional arg
prctrl review-time 4821
prctrl review-time 4821,4815,4809

# Estimate all pending reviews
prctrl review-time --all

# Group by time category for session planning
prctrl review-time --all --grouped

# Show priority scores with estimates
prctrl review-time --all --priority

# Filter by repository
prctrl review-time --all --repo my-repo

# Filter by author
prctrl review-time --all --author alice

# Combine filters
prctrl review-time --all --repo api --author alice --priority

# Filter by age
prctrl review-time --all --since-days 7

# Get JSON output for scripting
prctrl review-time --all --json

Output

⏱️  Review Time Estimates — 5 PRs, ~2.5h total
───────────────────────────────────────
  M  Fix authentication bug  #4821  myorg/repo
     👤 alice  •  📦 M (340 lines)  •  ⏱️ 15 min  🟡 moderate
     ★★★☆☆  ⭐3

  XL Refactor API gateway  #4815  myorg/repo
     👤 bob  •  📦 XL (1200 lines)  •  ⏱️ 1.8h  🔴 lengthy
     ★★★★★  ⭐5
...

Tips

• Sort by time descending (longest first) for session planning
• Combine with --json for spreadsheet导入
• Use quick category PRs forbetween-meeting slots
• Large PRs (>1h) are good candidates for delegation or pairing

review-velocity

Analyze how quickly PRs get reviewed — average time-to-review, distribution breakdown, and bottleneck detection.

See how fast (or slow) your team is at reviewing PRs. review-velocity calculates the time from PR creation to when you submitted your review, then breaks it down by time buckets and identifies which repositories or authors create the slowest reviews.

When to Use

• End of sprint: “Are we reviewing fast enough?”
• Identify bottlenecks: “Which repos/authors take forever to review?”
• Set SLAs: “What a reasonable review time target?”
• Track improvement: “Did our new process help?”

Synopsis

prctrl review-velocity [OPTIONS]

Options

Examples

# Standard 30-day velocity analysis
prctrl review-velocity

# Quick 7-day snapshot
prctrl review-velocity --days 7

# With bottleneck analysis (see slowest repos/authors)
prctrl review-velocity --bottlenecks

# With priority breakdown (correlate priority scores with review speed)
prctrl review-velocity --priority

# Combine all analysis options
prctrl review-velocity --bottlenecks --priority

# Filter by specific repository
prctrl review-velocity --repo backend

# Filter by specific author
prctrl review-velocity --author alice

# Combine filters with bottleneck analysis
prctrl review-velocity --repo api --bottlenecks

# Only PRs created in the last 14 days (regardless of when reviewed)
prctrl review-velocity --since-days 14

# Show velocity for a specific PR
prctrl review-velocity --pr 123

# Combine --since-days with other filters
prctrl review-velocity --since-days 7 --repo backend --bottlenecks

# JSON for dashboards
prctrl review-velocity --json | jq '.avg_hours_to_review'

Output Example

⚡ Review Velocity — last 30 days
─────────────────────────────────────────────

  📊 Summary (23 PRs reviewed)
     Average time to review:  18.4 hours
     Median time to review:    12.0 hours
     Fastest review:           0.5 hours
     Slowest review:           72.0 hours

  ⏱️  Time Distribution
     < 4h:       4 (17.4%)  ▓▓▓▓░░░░░░░░░░░░░░
     4-24h:      8 (34.8%)  ▓▓▓▓▓▓▓░░░░░░░░░░
     1-3d:       7 (30.4%)  ▓▓▓▓▓▓▓░░░░░░░░░
     > 3d:       4 (17.4%)  ▓▓▓▓░░░░░░░░░░░░░░

  ⭐ Priority vs Review Time
     ⭐⭐⭐⭐⭐  5 PRs  28.3h avg  ████████████
     ⭐⭐⭐⭐    8 PRs  14.2h avg  ████████
     ⭐⭐⭐     10 PRs  8.5h avg   █████
     ⭐⭐        0 PRs   0.0h avg
     ⭐         0 PRs   0.0h avg

  🐢 Bottleneck Analysis — by Author
     (slowest average review time)
     alice     ██████████  36.2h avg  (5 PRs)
     bob       ████████    28.1h avg  (8 PRs)
     carol     ███████      22.4h avg  (4 PRs)

  🐢 Bottleneck Analysis — by Repository
     (slowest average review time)
     backend   ██████████  32.1h avg  (12 PRs)
     frontend  ███████      18.5h avg  (7 PRs)
     shared    ████        8.2h avg   (4 PRs)

  💡 Use `--bottlenecks` to see which repos/authors take longest
  💡 Use `--priority` to correlate priority with review speed
  💡 Use `--json` for machine-readable output
─────────────────────────────────────────────

How It Works

Review velocity reads the processed review files saved in your output directory (default: ./reviews/). Each file contains both Created and Reviewed on timestamps, allowing calculation of the review time in hours.

Filters are applied efficiently:

• --since-days filter is checked before expensive parsing (early exit)
• --days filter then filters by review date
• --repo and --author filters are applied last for precise filtering

Time buckets:

• < 4h — Same day reviews (fast turnaround)
• 4-24h — Next day reviews (typical)
• 1-3d — Multi-day reviews (getting slow)
• > 3d — Stale reviews (bottleneck indicator)

Bottleneck analysis shows which authors or repositories have the highest average review times, helping identify process or knowledge gaps.

Priority vs Review Time (with --priority flag) shows how long high vs low priority PRs take to review. This helps answer questions like “Are we prioritizing urgent reviews?”

Tips

• Requires review files from delegate command
• Use --days 7 for weekly view, --days 90 for quarterly context
• Track your velocity over time to see if process changes help
• Pair with trends for complete review analytics
• Use --priority to see if critical PRs are getting the attention they deserve

trends

Analyze your review trends over time — velocity, week-over-week changes, top authors.

See how your review patterns evolve. How fast are you reviewing? Is your backlog growing or shrinking? Who’s sending the most PRs your way?

When to Use

• End-of-sprint check: “Am I keeping up with reviews?”
• Personal metrics: track your review velocity over time
• Team health: spot if backlog is growing

Synopsis

prctrl trends [OPTIONS]

Options

Examples

# Standard 30-day trend analysis
prctrl trends

# Quick 7-day snapshot
prctrl trends --days 7

# Focus on top 5 authors/repos
prctrl trends --limit 5

# Filter by repository
prctrl trends --repo frontend

# Filter by author
prctrl trends --author alice

# Combine filters
prctrl trends --repo backend --author bob

# Only show recent PRs (created in last 7 days)
prctrl trends --since-days 7

# Combine filters with since-days
prctrl trends --repo frontend --since-days 14

# JSON for dashboards/scripts
prctrl trends --json | jq '.avg_per_day'

# Show top PRs by priority score
prctrl trends --priority

# Show trends for a specific PR
prctrl trends --pr 123

Output Example

📈 Review Trends — last 30 days

  📊 Summary
     Total reviews:       47
     Daily average:      1.6 PRs/day
     Lines reviewed:     +2840 / -1230
     Avg PR size:        +60 / -26

  📅 Week-over-Week
     📈 This week: 12   Previous: 9   Change: +33.3%

  📈 Daily Activity (last 14 days)
     03-21  ████████░░░░░░░░░░░░░  8
     03-22  ██████████████░░░░░░░  12
     ...

  👥 Top Authors (by PR count)
     alice      14
     bob        11
     carol       9

  📁 Top Repositories
     frontend    18
     backend    15
     shared      8

  ⭐ Top PRs by Priority
     ⭐⭐⭐⭐⭐  #234  Bug fix in auth middleware (frontend)
     ⭐⭐⭐⭐⭐  #189  Refactor database layer (backend)
     ⭐⭐⭐⭐   #201  Update API documentation (shared)

How It Works

Trends reads the processed review files saved in your output directory (default: ./reviews/). Each review file contains metadata about when it was reviewed, who authored it, and how large it was — trends aggregates this data to surface patterns.

The week-over-week comparison tells you if your review throughput is increasing or decreasing. The sparkline chart gives you a visual feel for daily rhythm — are you batch-reviewing on certain days?

Tips

• Requires review files from delegate command (run prctrl delegate first to generate them)
• Use --days 7 for a tight weekly view, --days 90 for quarterly context
• Pipe to jq for integration with monitoring dashboards

digest

Generate a shareable weekly digest of your pending PR reviews — perfect for Slack, Teams, or email.

Unlike report (which shows what you’ve already reviewed), digest gives you a snapshot of what’s currently waiting, grouped by age, repository, and author.

When to Use

• Monday morning: “Let me share the team digest in Slack”
• Before a standup: “Quick status check for the channel”
• Weekly wrap-up: “Here’s what’s pending heading into the weekend”
• Stakeholder update: “Here’s a plain-text summary of review load”

Synopsis

prctrl digest [OPTIONS]

Options

Examples

# Pretty terminal digest
prctrl digest

# Shorter lookback (last 3 days)
prctrl digest --days 3

# Raw Markdown for pasting into Slack
prctrl digest --raw

# Raw Markdown with custom window
prctrl digest --days 14 --raw

# Filter by repository
prctrl digest --repo api

# Filter by author
prctrl digest --author alice

# Show priority scores and most urgent PR
prctrl digest --priority

# Combined: raw markdown filtered by repo with priority
prctrl digest --raw --repo backend --priority

# Only show PRs created in the last 3 days (recent PRs)
prctrl digest --since-days 3

# Only show PRs older than 7 days (neglected PRs)
prctrl digest --older-than 7

Output Examples

Terminal output

📋 Weekly Review Digest — last 7 days
─────────────────────────────────────────────

  📊 Summary
     Total PRs:          12
     Lines changed:      +2847 / -1203
     🚨 Overdue (15d+):  2

  ⏱️  Age Breakdown
     🆕 New: 3
     🌱 Fresh: 4
     ⏳ Aging: 2
     🔥 Stale: 1

  📁 By Repository (top 5)
     api-gateway: 4
     frontend: 3
     shared-libs: 2

  👥 By Author (top 5)
     alice: 4
     bob: 3
     carol: 2

  🚨 Overdue PRs (15d+)
     #4821 fix: critical auth bug — 18d old
     #4798 refactor: legacy cache layer — 16d old

─────────────────────────────────────────────
  💡 Use `--raw` to get Markdown output for Slack/Teams

With --priority flag

📋 Weekly Review Digest — last 7 days
─────────────────────────────────────────────

  📊 Summary
     Total PRs:          12
     Lines changed:      +2847 / -1203
     🚨 Overdue (15d+):  2

  🚨 Most Urgent:
    fix: critical auth bug  #4821  ⭐⭐⭐⭐⭐
    👤 alice  •  📦 1247 lines  •  ⏱️ 18d  •  api-gateway

  ⭐ Priority Breakdown:
     ⭐⭐⭐⭐⭐  2 PR(s)  •  oldest: 18d  •  +2340/-892 lines
     ⭐⭐⭐⭐   3 PR(s)  •  oldest: 10d  •  +847/-423 lines
     ⭐⭐⭐    4 PR(s)  •  oldest: 5d  •  +432/-156 lines
     ⭐⭐     2 PR(s)  •  oldest: 2d  •  +156/-89 lines
     ⭐      1 PR(s)  •  oldest: 0d  •  +72/-43 lines

─────────────────────────────────────────────
  💡 Use `--raw` to get Markdown output for Slack/Teams
  💡 Use `--priority` to show priority scores and most urgent PR

Raw Markdown output (--raw)

## 📋 Review Digest — last 7 days

**Total:** 12 PRs | **+2847** / **-1203** lines | **Overdue:** 2

### By Repository
- **api-gateway**: 4 PR(s)
- **frontend**: 3 PR(s)
- **shared-libs**: 2 PR(s)

### By Author
- **alice**: 4 PR(s)
- **bob**: 3 PR(s)
- **carol**: 2 PR(s)

### Age Breakdown
- 🆕 **New**: 3 PR(s)
- 🌱 **Fresh**: 4 PR(s)
- ⏳ **Aging**: 2 PR(s)
- 🔥 **Stale**: 1 PR(s)

### 🚨 Overdue (15d+)
- [api-gateway#4821](https://github.com/org/api-gateway/pull/4821) *fix: critical auth bug* — 18d old
- [shared-libs#4798](https://github.com/org/shared-libs/pull/4798) *refactor: legacy cache layer* — 16d old

Tips

• Use --raw when posting to Slack, Teams, or email — the Markdown renders nicely in all three
• Pipe to pbcopy to copy to clipboard: prctrl digest --raw | pbcopy
• Use --days 1 for a daily standup digest instead of weekly
• Use --priority to identify the most urgent PR at a glance
• Age buckets: 🆕 New 0-1d · 🌱 Fresh 2-3d · ⏳ Aging 4-7d · 🔥 Stale 8-14d · 💀 Overdue 15d+
• Combine filters for targeted digests: digest --repo backend --author alice --priority
• Use --since-days 7 to show only recently created PRs
• Use --older-than 7 to focus on neglected PRs waiting 7+ days
• --since-days and --older-than can be combined but --since-days takes precedence

export

Export pending reviews to CSV, Markdown, or JSON format.

Perfect for manager reports, team dashboards, or integrating with other tools.

When to Use

• Weekly reports: “Export my queue for the team”
• Spreadsheet analysis: “Open in Excel/Google Sheets”
• Team dashboards: “Post to Slack/Notion”
• Manager summaries: “Show backlog size and aging”
• Scripting: “Parse exports in automated workflows”

Synopsis

prctrl export [OPTIONS]

Options

Available Columns

Examples

# Export all pending reviews as CSV (prints to stdout)
prctrl export

# Export to a file
prctrl export --output pending-reviews.csv

# Export as Markdown table (great for Notion/Slack)
prctrl export --format markdown --output report.md

# Export only specific columns
prctrl export --columns repo,title,author,age

# Export with priority scores included
prctrl export --priority --output prioritized-reviews.csv

# Export as JSON for scripting or API integration
prctrl export --json --output reviews.json

# Export as JSON with priority scores
prctrl export --json --priority --output reviews.json

# Export with fresh data (bypasses session cache)
prctrl export --all --output full-report.csv

# Export only PRs from a specific repository
prctrl export --repo backend --output backend-reviews.csv

# Export only PRs by a specific author
prctrl export --author alice --output alice-reviews.csv

# Export only PRs created in the last 7 days
prctrl export --since-days 7 --output recent-reviews.csv

# Export a specific PR by number
prctrl export --pr 4821

# Export multiple specific PRs
prctrl export --pr-numbers 4821,3156,2890

# Combine filters with other options
prctrl export --repo frontend --author alice --format markdown --output report.md

Output Examples

CSV Format (default)

repo,number,title,author,size,age,draft,url
backend,4821,feat: add dark mode,alice,+89/-12,2d,no,https://github.com/org/backend/pull/4821
frontend,3156,fix: login timeout,bob,+234/-45,4d,no,https://github.com/org/frontend/pull/3156

CSV with Priority

repo,number,title,author,size,age,draft,url,priority
backend,4821,feat: add dark mode,alice,+89/-12,2d,no,https://github.com/org/backend/pull/4821,3
frontend,3156,fix: login timeout,bob,+234/-45,4d,no,https://github.com/org/frontend/pull/3156,4

Markdown Format

| Repo | # | Title | Author | Size | Age | Draft | URL |
|------|---|-------|--------|------|-----|-------|-----|
| `backend` | #4821 | feat: add dark mode | alice | +89/-12 | 2d | no | [link](https://...) |

JSON Format

[
  {
    "repo": "backend",
    "number": 4821,
    "title": "feat: add dark mode",
    "author": "alice",
    "size": "+89/-12",
    "age_days": 2,
    "draft": false,
    "url": "https://github.com/org/backend/pull/4821",
    "priority_score": 3
  }
]

Tips

• Use --output to write directly to a file instead of piping
• Markdown format is great for pasting into Slack messages or Notion docs
• JSON format is ideal for scripting and API integrations
• Combine with --priority to include urgency scores in exports
• Combine with --all to ensure you have the latest data
• Column order is preserved in CSV/Markdown output

history

Search and filter your review history from processed review files.

The history command lets you dig into your past review activity with powerful filtering — by repository, author, review state (approved/changes requested/commented), and time window. It reads from the review files created when you run prctrl list or delegate reviews.

When to Use

• Research: “Which PRs did I review for the frontend team last month?”
• Author follow-up: “What reviews did I give to alice’s PRs this week?”
• State analysis: “Show me all the PRs where I requested changes”
• Reporting: “Generate a list of all my reviews for the past quarter”

Synopsis

prctrl history [OPTIONS]

Options

Examples

# View your last 30 days of review history
prctrl history

# Show only reviews for the frontend repo
prctrl history --repo frontend

# Show reviews where you requested changes
prctrl history --state CHANGES_REQUESTED

# Find all reviews of alice's PRs in the last 90 days
prctrl history --author alice --days 90

# Combine filters - reviews of bob's PRs in backend repo with changes requested
prctrl history --author bob --repo backend --state CHANGES_REQUESTED

# Get JSON for scripting
prctrl history --json --days 7

# Limit to 10 most recent
prctrl history --limit 10

Output

📜 Review History (last 30 days)
──────────────────────────────────────────────────
  Total matching entries: 47

  ✅ APPROVED (32 PRs)
    #4821  Fix authentication bug           myorg/frontend (2d ago)
    #4815  Update dependencies              myorg/shared (3d ago)
    ...

  🔁 CHANGES_REQUESTED (10 PRs)
    #4802  Refactor API gateway            myorg/backend (5d ago)
    ...

  💬 COMMENTED (5 PRs)
    #4798  Add new feature                  myorg/frontend (1w ago)
    ...

──────────────────────────────────────────────────
  💡 Use `--json` for scripting | `--repo`, `--author`, `--state` to filter

Tips

• Review history is built from .md files in your output directory (default: ./reviews)
• Run prctrl list first to populate review files
• Filter combinations are ANDed together (repo AND author AND state)
• Use --json for integration with external tools or dashboards
• The --limit flag helps when you just need the most recent N entries

Related Commands

• activity — GitHub-sourced review activity (uses GitHub API directly)
• report — Weekly review summary reports
• stats — Statistics about pending reviews

config

Manage PRCtrl configuration settings.

Create, view, and update your local configuration file.

When to Use

• Initial setup: prctrl config init
• Check current config: prctrl config show
• Update specific fields: prctrl config update --token xxx

Configuration File Location

The configuration file is stored at: ~/.prctrl/config.toml

Synopsis

# Interactive configuration setup
prctrl config init
prctrl config init --force   # Overwrite existing without prompting

# Display current configuration
prctrl config show

# Update specific configuration fields
prctrl config update --token YOUR_GITHUB_TOKEN
prctrl config update --org your-org --repos owner/repo1,owner/repo2
prctrl config update --teams team-slug-1,team-slug-2

Subcommands

init

Create a new configuration file interactively.

prctrl config init
prctrl config init --force   # Overwrite without prompting

You’ll be prompted for:

• GitHub Token (required)
• GitHub Username (required)
• GitHub Organization (required)
• GitHub Repositories (optional, comma-separated)
• GitHub Teams (optional, comma-separated slugs)
• Crew Members (optional, comma-separated usernames)
• Anthropic API Key (optional)

show

Display the current configuration file contents.

prctrl config show

update

Update specific configuration fields without full re-initialization.

prctrl config update --token YOUR_TOKEN
prctrl config update --org your-org
prctrl config update --repos owner/repo1,owner/repo2
prctrl config update --teams team-slug-1,team-slug-2
prctrl config update --crew username1,username2
prctrl config update --api-key YOUR_API_KEY

All flags are optional. Only provided flags will be updated.

Options

init Options

show Options

No additional options.

update Options

Examples

Initial Setup

$ prctrl config init
📝 Creating new configuration file...
   Path: /home/user/.prctrl/config.toml

GitHub Token (PRCTRL_GITHUB_TOKEN or GITHUB_TOKEN): ghp_xxxxxxxxxxxx
GitHub Username (PRCTRL_GITHUB_USERNAME or GITHUB_USERNAME): myusername
GitHub Organization (PRCTRL_GITHUB_ORG or GITHUB_ORG): my-org
GitHub Repositories (comma-separated, e.g. owner/repo1,owner/repo2) (optional): owner/repo1,owner/repo2
GitHub Teams (comma-separated slugs, optional): my-team,other-team
Crew Members (comma-separated usernames, optional): alice,bob
Anthropic API Key (optional):

✅ Configuration saved successfully!

Check Current Config

$ prctrl config show
📄 Configuration File: /home/user/.prctrl/config.toml

--------------------------------------------------
# PRCtrl Configuration File
# Created at: 2024-01-15T10:30:00+00:00

[github]
token = "ghp_xxxxxxxxxxxx"
username = "myusername"
org = "my-org"
repos = ["owner/repo1", "owner/repo2"]
teams = ["my-team", "other-team"]
crew_members = ["alice", "bob"]
--------------------------------------------------

Update Specific Fields

$ prctrl config update --org new-org --teams new-team
✅ Configuration updated successfully!
   Path: /home/user/.prctrl/config.toml

Notes

• The configuration file is stored in TOML format
• Environment variables (PRCTRL_* or GITHUB_*) take precedence over config file values
• Use prctrl config init --force to regenerate the entire config file

Reviews Location

When you run prctrl list or other commands, review files are stored in:

~/.prctrl/reviews/

This keeps your reviews organized with your config.

clean

Remove all past review files from the output directory.

Keep your reviews folder tidy by purging old output.

When to Use

• Weekly cleanup: “Fresh start”
• Before report: “Start clean for new report period”

Synopsis

prctrl clean
prctrl clean --dry-run
prctrl clean -n          # short form for dry-run
prctrl clean --quiet    # suppress output

Options

Tips

• Only deletes files in your local output directory
• Does not affect GitHub data
• Always use --dry-run first if you’re unsure what will be deleted