Enhanced PR Checks Monitor with Runtime and Latency Tracking

[chicks-net]

Problem

The GitHub CLI's gh pr checks --watch command is functional but frustrating in practice. When you push code and want to monitor your CI pipeline, you're stuck watching a command that doesn't handle reality well:

• Startup delay blindness: Actions can take 30-90 seconds to even start after you create a PR. During this time, --watch just shows nothing or stale data, leaving you wondering if something broke or if GitHub is just being slow.

• No runtime visibility: Once checks are running, you can't see how long they've been running. Is that test suite taking its usual 3 minutes or has it been stuck for 15? You have no idea without opening a browser.

• Missing latency data: You can't tell the difference between "job started immediately" vs "job waited in queue for 5 minutes." This is valuable context when deciding whether to wait or go get coffee.

The web UI has some of this information, but buried in multiple clicks. You started with the terminal, you want to stay in the terminal. This tool would bridge that gap with a better CLI experience.

Technical Requirements

Core Functionality

• Monitor PR check runs in real-time via GitHub API
• Display check status with:
  • Current state (queued, in_progress, completed, etc.)
  • Queue/latency time (time between PR creation and job start)
  • Elapsed runtime (time since job started)
  • Final duration (when complete)
  • Outcome (success, failure, cancelled, skipped)
• Handle the startup delay gracefully with useful feedback
• Update display in-place (not scrolling spam)
• Color-coded output for quick visual scanning
• Exit with appropriate status code (0 for all passed, 1 for any failure)

Example Output

PR #123: Add new feature
Branch: chicks/2026-02-08-new-feature

Startup Phase (37s elapsed):
  ⏳ Waiting for Actions to start...
  💡 GitHub typically takes 30-90s to queue jobs after PR creation

Running Checks:
  ✓ markdownlint          [completed in 12s]        (queued: 41s)
  ✓ shellcheck            [completed in 8s]         (queued: 41s)
  ⏳ go-test              [running: 2m 34s]         (queued: 45s)
  ⏳ integration-tests    [running: 1m 12s]         (queued: 52s)
  ⏸️  deploy-preview      [queued: 3m 15s]          (waiting for tests)

Last updated: 2s ago

Configuration

• Auto-detect current PR from branch (like gh pr checks does)
• Accept PR number as argument: gh-pr-watch 123
• Accept PR URL as argument
• Support configuration file (~/.config/gh-pr-watch/config.yaml or similar):
  • Refresh interval (default: 3-5 seconds)
  • Color scheme preferences
  • Notification preferences (alert on completion, failure, etc.)
  • Expected/baseline durations for common jobs (to highlight anomalies)
  • Output format (compact, detailed, JSON)

Notifications (optional but valuable)

• Desktop notification when all checks complete
• Optional sound/bell on completion
• Webhook support for posting to Slack/Discord/etc.
• Different notification based on outcome (success vs. failure)

Implementation Considerations

GitHub API Usage

• Use GitHub REST API or GraphQL API for check runs
• Respect rate limits (authenticated requests get 5000/hour)
• Cache results to minimize API calls
• Use conditional requests (ETag/If-Modified-Since) where possible
• Handle API errors gracefully (rate limit, network issues, etc.)

Terminal UI

• Use ANSI escape codes for color and cursor positioning
• Support both fancy mode (cursor positioning, colors) and plain mode (for CI logs)
• Detect terminal capabilities (detect if stdout is a TTY)
• Handle terminal resize gracefully
• Consider using a TUI library for robustness:
  • Go: bubbletea, termui, or simple fmt with ANSI codes
  • Rust: crossterm, tui-rs, indicatif
  • Bash: just ANSI codes (tput, printf)

State Management

• Track state changes to avoid unnecessary redraws
• Calculate deltas: queued time = start_time - created_time, runtime = now - start_time
• Handle out-of-order updates (API might return stale data)
• Remember first-seen time to track "startup phase"

Timing Considerations

• Clock skew: GitHub timestamps are server-side, local clock might differ
• Timezone handling: convert GitHub UTC times to local time if displaying absolute times
• Poll interval: balance between freshness and API rate limits (3-5s seems reasonable)

Edge Cases

• PR with no checks configured (helpful error message)
• Checks that get re-run (show both attempts?)
• Checks that are cancelled or skipped
• Required vs. optional checks (differentiate visually?)
• Multiple concurrent PRs (support watching multiple PRs at once?)

Possible Tech Stack

Language (per project preferences)

• Go: Excellent choice - single binary, good GitHub API libraries (go-github), decent TUI libraries, fast startup
• Rust: Also good - great performance, type safety, excellent error handling; octocrab for GitHub API, crossterm/indicatif for UI
• Bash: Could work for simple version, but complex for good TUI; would need jq for JSON parsing and curl for API calls
• Perl: Could work but not ideal for modern API consumption and TUI

Recommendation: Go - best balance of project preference, ecosystem maturity, and deployment simplicity

GitHub API Client Libraries

• Go: google/go-github (mature, well-maintained)
• Rust: octocrab (actively developed, good API coverage)
• Bash: curl + jq (manual but flexible)

TUI/Terminal Libraries

• Go: charmbracelet/bubbletea (modern, elegant), gizak/termui (dashboard-style), or raw ANSI
• Rust: crossterm (low-level), tui-rs (higher-level), indicatif (progress bars)
• Bash: tput, printf with ANSI escape codes

Notifications

• Cross-platform: gen2brain/beeep (Go), notify-rust (Rust)
• macOS: osascript / terminal-notifier
• Linux: notify-send (via D-Bus)
• Windows: Windows Toast notifications

Integration with gh CLI

Option 1: Standalone Binary

• Ship as gh-pr-watch (GitHub CLI automatically recognizes gh-* executables as extensions)
• Users install by putting binary in PATH
• Invoke as gh pr watch (space, not dash) or gh-pr-watch directly

Option 2: gh Extension

• Package as official gh extension
• Install via gh extension install user/gh-pr-watch
• Better discovery, automatic updates
• More setup overhead (manifest, documentation)

Recommendation: Start with Option 1 (standalone), migrate to Option 2 once stable

Future Enhancements

• Historical comparison: "This run is 2x slower than average"
• Flamegraph/timeline view: Visual representation of job parallelism and dependencies
• Log streaming: Show live logs from failing jobs without leaving terminal
• Job step breakdown: Show individual steps within a job with their timing
• Retry failed jobs: Integrate with gh to trigger re-runs
• Custom alerting rules: "Alert me if runtime > 10 minutes" or "Alert only on failure"
• Multi-PR dashboard: Watch multiple PRs simultaneously in split view
• Export to formats: JSON, CSV, or markdown summary for pasting in PR comments
• Baseline learning: Automatically learn typical job durations and alert on anomalies
• Cost tracking: Estimate Actions minutes consumed (for usage monitoring)
• Workflow visualization: Show dependency graph of jobs
• Integration with Waybar/Polybar: Status bar widget showing current PR check status

Nice-to-Haves

• Man page documentation
• Shell completion (bash, zsh, fish)
• Update checker (notify when new version available)
• Verbose/debug mode for troubleshooting API issues
• Dry-run mode to test configuration without watching
• Configuration wizard for first-time setup
• Pre-built binaries for major platforms (Linux, macOS, Windows)
• Homebrew formula for easy installation on macOS
• Docker container for running in CI or constrained environments

Success Criteria

• Handles "waiting for Actions to start" with clear user feedback
• Shows elapsed runtime for all running checks
• Shows queue latency for all jobs (time from PR to job start)
• Updates smoothly without terminal flicker or spam
• Exits with correct status code for CI integration
• Works with public and private repositories (authenticated)
• Gracefully handles API errors and rate limits
• Performant enough to check every 3-5 seconds without lag
• Clear documentation and installation instructions
• Single binary with no runtime dependencies (for Go/Rust)

Prior Art / Related Tools

• gh pr checks --watch: The baseline we're improving on
• hub ci-status: Similar functionality for older hub CLI
• GitHub Actions web UI: Full-featured but requires browser
• Various CI dashboard tools (Jenkins BlueOcean, CircleCI, etc.): Inspiration for UX patterns

Notes

This is fundamentally a UX improvement over existing tooling. The data is all available via GitHub API, but the presentation in gh pr checks --watch leaves much to be desired. The most valuable additions are:

1. Startup delay handling: Just acknowledging "yes, it's normal for this to take a minute" reduces anxiety
2. Runtime display: Being able to see "this is taking longer than usual" helps decide whether to wait or investigate
3. Latency visibility: Helps understand whether slowness is your code or GitHub's infrastructure

The tool should feel calm and informative rather than anxious and noisy. Good terminal UI is about providing the right information at the right time without overwhelming the user.

This also serves as a good template for other "watch GitHub thing" tools - releases, deployments, issue updates, etc.

[chicks-net]

@claude can gh extensions add second level commands like gh pr watch or are extensions limited to adding top-level subcommands?

[claude]

Claude finished @chicks-net's task in 1m 25s —— View job

---

Answer about GitHub CLI extension command structure

• Research GitHub CLI extension command structure capabilities
• Provide answer about second-level commands

---

Current Status: Extensions are limited to top-level commands

Short answer: As of now, gh extensions are limited to adding top-level subcommands only. An extension cannot add a second-level command like gh pr watch. However, nested extension support is a planned feature.

How Extensions Currently Work

When you create a gh extension:

1. Repository naming: Your repository must be named gh-<extension-name> (e.g., gh-pr-watch)
2. Executable naming: Must contain an executable with the same name at the root
3. Invocation: Users run it as gh <extension-name> (e.g., gh pr-watch with a dash, not gh pr watch with a space)
4. Limitation: Extensions cannot override core gh commands or nest under them

Why gh pr watch Won't Work (Yet)

The gh pr command is a core GitHub CLI command. Currently, extensions cannot:

• Override core commands
• Add subcommands under core commands like pr, issue, repo, etc.

So you'd need to name your extension something like gh-pr-watch and users would invoke it as:

gh pr-watch        # This works (note the dash)
gh pr watch        # This does NOT work - 'watch' isn't a core pr subcommand

Future: Nested Extensions (Planned)

According to GitHub's documentation and blog posts, the GitHub CLI team intends to add support for nested extensions - specifically allowing "an extension called as a subcommand of an existing gh command like gh pr my-extension" to make third-party extensions fit more naturally into the command hierarchy.

There's active discussion about this, including a November 2025 GitHub issue proposing PR review helper commands nested under gh pr for AI agent workflows.

Recommendation for Your Project

For the PR checks monitor tool in issue #25, I'd recommend:

1. Name it gh-pr-watch (or similar) for the repository
2. Users invoke it as gh pr-watch (with dash)
3. Alternative naming: Consider gh-watch-pr or gh-checks-watch if you want different UX
4. Document clearly: Make it obvious in your README that it's gh pr-watch (dash) not gh pr watch (space)

When nested extension support eventually lands, you could potentially migrate to being invoked as gh pr watch, but that's not available yet.

Sources

• Creating GitHub CLI extensions - GitHub Docs
• GitHub CLI extension command reference
• New GitHub CLI extension tools - The GitHub Blog
• Add PR review helper commands under gh pr for inline comments and review flows (AI agent use cases) · Issue #12232 · cli/cli
• gh extension manual pages

---

| Branch: claude/issue-25-20260209-0610

[chicks-net]

@claude what are some synonyms of overseer or watcher that would be good for this project name?

[claude]

Claude finished @chicks-net's task in 29s —— View job

---

Naming suggestions for PR checks monitor

• Generate synonym suggestions for project name
• Provide organized list with context

---

Here are naming alternatives organized by theme:

Active Monitoring (implies continuous watching)

• gh-pr-sentinel - guard/watcher, protective connotation
• gh-pr-vigil - keeping watch, especially at night
• gh-pr-patrol - regular monitoring rounds
• gh-pr-monitor - straightforward, clear purpose
• gh-pr-guardian - protective oversight

Observation/Tracking Focus

• gh-pr-tracker - emphasizes following progress
• gh-pr-observer - neutral, scientific feel
• gh-pr-scout - reconnoitering, gathering intel
• gh-pr-witness - observing and recording
• gh-pr-surveyor - systematic examination

Status/Information Display

• gh-pr-status - direct, describes what it shows
• gh-pr-dashboard - implies comprehensive view
• gh-pr-radar - detection and tracking
• gh-pr-gauge - measuring/monitoring
• gh-pr-pulse - checking health/status

Steward/Management Theme

• gh-pr-steward - caretaker, responsible oversight
• gh-pr-keeper - maintains watch over
• gh-pr-custodian - guardian of process
• gh-pr-caretaker - attentive monitoring

Short/Punchy Options

• gh-pr-eye - simple, visual
• gh-pr-lens - focused view
• gh-pr-scan - quick check
• gh-pr-peek - lightweight observation
• gh-pr-wait - emphasizes the "waiting for checks" use case

My Recommendations:

1. gh-pr-sentinel - Strong, memorable, implies reliability and alertness. Good developer-tool vibe.
2. gh-pr-vigil - Poetic but appropriate for "keeping watch over long-running checks"
3. gh-pr-radar - Modern, implies detection and tracking with visual metaphor
4. gh-pr-pulse - Captures the "health check" aspect, short and memorable
5. gh-pr-scout - Lightweight feel, fits the "reconnaissance" nature of checking status

Considerations:

• Avoid names that are too long (gh-pr-guardian is 13 chars)
• Names should be easy to type and remember
• Should feel appropriate for a developer tool (not too whimsical)
• Should communicate purpose without deep explanation
• Check for naming conflicts with existing tools/extensions

Given the tool's emphasis on runtime tracking and latency visibility, names like sentinel, radar, or pulse seem particularly fitting as they imply active, continuous monitoring with timing awareness.

[chicks-net]

Started in fini-net/gh-observer#3

[chicks-net]

@claude How does the official github CLI find the workflow name during gh pr checks --watch ?

[claude]

Claude finished @chicks-net's task in 3m 35s —— View job

---

Researching GitHub CLI workflow name resolution

• Research GitHub CLI source code for check runs implementation
• Examine GitHub API endpoints used
• Understand workflow name resolution mechanism
• Provide detailed technical explanation

---

How gh pr checks --watch Finds Workflow Names

I've analyzed the GitHub CLI source code to understand exactly how workflow names are retrieved. Here's the complete technical breakdown:

1. GraphQL Query Structure

The GitHub CLI uses a GraphQL query (not REST API) to fetch check information. The key query path for workflow information is:

statusCheckRollup: commits(last: 1) {
    nodes {
        commit {
            statusCheckRollup {
                contexts(first:100) {
                    nodes {
                        __typename
                        ...on CheckRun {
                            name
                            checkSuite {
                                workflowRun {
                                    workflow {
                                        name  # ← Workflow name retrieved here
                                    }
                                }
                            }
                            status
                            conclusion
                            startedAt
                            completedAt
                            detailsUrl
                        }
                    }
                }
            }
        }
    }
}

2. GitHub API Object Hierarchy

The workflow name is accessed through this nested path:

Commit
  → StatusCheckRollup
    → CheckContext (CheckRun)
      → CheckSuite
        → WorkflowRun
          → Workflow
            → name

3. Data Structure in Go

The GitHub CLI maps this to Go structs:

type CheckContext struct {
    Name        string     
    CheckSuite  CheckSuite 
    // ...
}

type CheckSuite struct {
    WorkflowRun WorkflowRun
}

type WorkflowRun struct {
    Workflow Workflow
}

type Workflow struct {
    Name string  // ← This is the workflow name
}

Workflow name is accessed as: CheckContext.CheckSuite.WorkflowRun.Workflow.Name

4. Display Format

The CLI formats check runs as: workflow-name/check-name

For example: CI/test-suite where "CI" is the workflow name and "test-suite" is the check run name.

If the workflow name is empty (for legacy status checks), only the check name is displayed.

5. Key Implementation Points

• Single API call: The workflow name comes in the same GraphQL response as check status—no separate lookup needed
• API endpoint: https://api.github.com/graphql
• Two check types:
  • CheckRun - GitHub Actions workflow runs (have workflow names)
  • StatusContext - Legacy commit statuses (no workflow names)
• Feature detection: Older GitHub Enterprise Server versions may not support the workflowRun field
• Deduplication: Multiple executions of the same check are filtered to show only the most recent

6. For Your Implementation

When building gh-observer, you can use the same approach:

1. Use GraphQL API (more efficient than REST for nested data)
2. Query the statusCheckRollup field on the commit
3. Access workflow name via: checkRun.checkSuite.workflowRun.workflow.name
4. Handle both check types: CheckRun (Actions) and StatusContext (legacy)
5. Format as: workflow/check-name for clarity

The source code for the gh pr checks command is in the cli/cli repository:

• GraphQL query: pkg/cmd/pr/checks/checks.go
• Data structures: api/queries_pr.go
• Display logic: pkg/cmd/pr/checks/output.go

---

[chicks-net]

https://github.blog/developer-skills/github/new-github-cli-extension-tools/ and https://docs.github.com/en/github-cli/github-cli/creating-github-cli-extensions are informative

[chicks-net]

Today's tasks:

• display time since push
• display UTC time
• display error logs
• ?? display descriptions (for super-linter) Feature: Display check run descriptions gh-observer#22
• test as an extension
• release GHA
• add repo tag to make it a github-cli extension
• asciinema demo
• post on related github issues