gh-observer

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
• ✅ 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

  15s ✗ MarkdownLint / lint                             5s
   .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
  15s ✓ CUE Validation / verify                         6s
  15s ✓ Checkov / scan                                 27s
  15s ✓ Claude Code Review / claude-review          3m 52s
  15s ✓ Lint GitHub Actions workflows / actionlint      8s
  39s ✓ Checkov                                         2s

Press q to quit

Example Animations

Thanks to asciinema we can show you:

PR that was already merged

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

gh observer 123

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.

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