gh observer

A GitHub PR check watcher that improves on gh pr checks --watch by showing runtime metrics, queue latency, and better handling of startup delays.

Why?

The existing gh pr checks --watch doesn't show how long checks have been running, doesn't handle the 30-90s startup delay well, and doesn't show queue latency. This creates anxiety when watching CI runs - "is it stuck or just slow?"

Features

• ⏱️ Runtime metrics - Shows elapsed time: 3m 52s tells you exactly how long checks have been running
• ⏳ Queue latency - Displays wait time: 15s shows how long GitHub queued the job before starting
• 🔄 Real-time updates - Auto-refreshes every 5s (configurable) without manual polling
• ⚡ Startup phases - Helpful messages like "Waiting for Actions to start..." during the 30-90s GitHub delay
• 🛡️ Rate limits - Backs off automatically when approaching API limits to avoid interruptions
• 📊 Historical averages - Shows average runtime for each job based on recent completed runs, so you know if things are taking longer than usual
• ⚡ --quick mode - Skip the historical averages fetch when you just want a fast snapshot
• ✅ CI-friendly - Returns exit codes (0=success, 1=failure) for script automation

Example Output

PR #123: Add new feature

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

PR #5: 🔶 [claude] /init 21:04:15 UTC
Updated 0s ago  •  Pushed 43h 8m 11s ago

Startup   Workflow/Job                                Duration   Avg

  15s ✗ MarkdownLint / lint                             5s        6s
   .github:13 - Failed with exit code: 1
   CLAUDE.md:100 - Lists should be surrounded by blank lines: CLAUDE.md:100 MD032/blanks-around-lists Lists should be surr

  15s ✓ Auto Assign / run                               5s        4s
  15s ✓ CUE Validation / verify                         6s        7s
  15s ✓ Checkov / scan                                 27s       31s
  15s ✓ Claude Code Review / claude-review          3m 52s   4m 10s
  15s ✓ Lint GitHub Actions workflows / actionlint      8s        9s
  39s ✓ Checkov                                         2s        2s

Press q to quit

Example Animations

Thanks to asciinema we can show you how our extension looks in practice. You can compare to old animations to see how we have evolved.

PR that was already merged

This shows in real-time (not accelerated) how it goes when you check out a PR that is already merged.

PR in remote repo that was already merged

Running gh observer https://github.com/MartinDelille/nautilus/pull/13 results in:

Again in real-time, but now checking out a PR on a repo that we do not have cloned locally. Note: it requires the full URL.

PR that was just created

This was sped up 2x. In this example, the Claude check fails, illustrating how error log output is integrated alongside the list of jobs.

PR that was just created with GHAs that use descriptions

The Super-Linter and a few other GitHub Actions utilize the description field to convey success or failure. Our extension doesn't show descriptions for successful checks and displays them for cases with errors to be consistent with the GitHub Actions that make it easier to show the right bit of the logs. Since we don't try to show the logs for super-linter, you're "stuck" clicking on the title of the job in your terminal and it will open up in your favorite web browser.

This was sped up 10x.

Installation

Install precompiled binary

The easiest way to install gh-observer is as a GitHub CLI extension:

gh extension install fini-net/gh-observer

This installs a precompiled binary for your platform - no Go toolchain required. To install a specific version:

gh extension install fini-net/gh-observer --pin v1.0.0

Or install via go install

If you prefer installing via Go:

go install github.com/fini-net/gh-observer@latest

Or build from source

To build from source:

git clone https://github.com/fini-net/gh-observer.git
cd gh-observer
just build

Usage

Auto-detect PR from current branch

gh observer

Watch specific PR in current repo

gh observer 123

Watch external PR by URL

You can watch checks on any public PR by passing the full URL - no need to clone the repo:

gh observer https://github.com/StackExchange/dnscontrol/pull/3941

This works for any GitHub PR URL and is useful for:

• Reviewing checks on a colleague's PR in another repo
• Monitoring upstream dependencies before merging
• Following CI status on projects you don't have cloned locally

Skip historical averages for a faster snapshot

If you just want a quick look without waiting for the historical averages fetch, use --quick (or -q):

gh observer --quick
gh observer -q 123

This skips the extra API calls for historical job runtimes and prints immediately. Useful when you're in a hurry or don't have the API budget to spare.

Use in CI pipelines

Our primary focus is on improving the interactive experience, but we also set the exit code for the process in a potentially useful way.

# Wait for checks to complete and exit with their status
gh observer && echo "All checks passed!"

Configuration

Create ~/.config/gh-observer/config.yaml to customize settings:

# Refresh interval for polling GitHub API
refresh_interval: 5s

# Color codes for terminal output (ANSI 256-color palette)
colors:
  success: 10  # Green - completed successfully
  failure: 9   # Red - completed with failure
  running: 11  # Yellow - currently in progress
  queued: 8    # Gray - waiting to start

See .config.example.yaml for reference.

Authentication

gh-observer uses GitHub authentication in this order:

1. GITHUB_TOKEN environment variable
2. gh CLI authentication (gh auth token)

Make sure you have either set up.

Supported Platforms

Precompiled binaries are available for:

• macOS: Intel (amd64) and Apple Silicon (arm64)
• Linux: x86-64 (amd64) and ARM64
• Windows: x86-64 (amd64)

All binaries include supply chain security attestations for verification.

Known Limitation: Live Logs for Slow Jobs

We'd love to show you live (non-error) logs while your jobs are still running — especially for jobs that take over a minute. Unfortunately, the GitHub Actions API no longer returns logs in real-time. The logs endpoint returns a 404 while a job is in progress and only serves logs after the job completes. This makes streaming or tailing job logs via the API impossible today.

Multiple attempts to work around this (see #127) have confirmed there is no viable alternative. GitLab supports this; GitHub does not (yet).

If live job logs would help your workflow, please upvote and comment on the community discussion to let GitHub know this matters. The more voices, the more likely we'll get a real-time log streaming API.

Development

This project uses just for task automation:

# Build the binary and install locally as gh extension
just build

# Run on current PR
gh observer

# Create a PR
just pr

# Merge a PR
just merge

Architecture

Built with:

• Bubbletea - TUI framework
• Lipgloss - Terminal styling
• go-github - GitHub API client
• Viper - Configuration management

See CLAUDE.md for detailed implementation notes. Read the linear walkthrough to get a detailed walkthrough of the code and to learn why some of the design choices were made.

Contributing

• Code of Conduct
• Contributing Guide includes a step-by-step guide to our development process.

Support & Security

• Getting Support
• Security Policy