ghud 0.2.4

GitHub Heads-Up Display — terminal dashboard for your portfolio repos

ghud

GitHub Heads-Up Display — a terminal dashboard for your portfolio repos.

ghud gives you quick, formatted access to your GitHub activity without verbose gh field specifications or opening a browser.

• Global dashboard — notifications, open PRs, merged PRs, issues, other activity
• Issue views — ghud i 42 for a rich issue display, ghud i for a list
• PR views — ghud pr 15 with check status, reviews, and comments
• Repo dashboard — ghud r for issues + PRs in the current repo
• Repo discovery — find repos missing from your portfolio config

Example

$ ghud
╭───────────────────────── New Issues From Others (3) ─────────────────────────╮
│  plinking_duck       Faster BCF/VCF reader for 'Free'              23d ago  │
│  duckdb_markdown     Would it be possible to add option to         50d ago  │
│                      write markdown with frontmatter data?                  │
│  duckdb_scalarfs     Curious about the extension usage             80d ago  │
╰──────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────── Your Open PRs (5) ──────────────────────────────╮
│  community-ext       Update sitting_duck to v1.4.0                      0d  │
│  fledgling           Extract conversation tools into MCP server    13d  1c  │
│  fledgling           Fix ReadLines returning empty table           18d  1c  │
│  community-ext       Update plinking_duck to v0.1.2                    21d  │
│  duckdb_tarfs        Port to DuckDB v1.4-andium                   40d  3c  │
╰──────────────────────────────────────────────────────────────────────────────╯

Installation

pip install ghud

Requires the GitHub CLI (gh) to be installed and authenticated.

Quick Start

# Global dashboard
ghud

# View issue #42 in the current repo
ghud i 42

# View PR #15 with full detail
ghud pr 15 --detail full

# List open issues across all portfolio repos
ghud i --repo all

# Repo dashboard for the current directory
ghud r

# Find repos not yet in your portfolio config
ghud discover --dry-run

Commands

Command	Alias	Description
ghud / ghud overview	ghud o	Global dashboard
ghud issue [N]	ghud i	List issues or view detail
ghud pr [N]		List PRs or view detail
ghud repo	ghud r	Repo-level dashboard
ghud discover		Find untracked repos
ghud serve		Start MCP server

Key Options

• --repo owner/repo — target a specific repo (--repo all for cross-repo)
• --detail brief|summary|standard|full — control detail level on issue/PR views
• --comments N — show last N comments (default: 3, or --comments all)
• --no-pager — disable pager
• --state open|closed|all — filter list views
• --limit N — max items in list views (default: 30)

Configuration

ghud determines your portfolio repos from one of two sources, in order:

1. ~/.mrconfig — if you use myrepos (mr) to manage your repos, ghud reads its manifest directly and derives each owner/repo from the stanza's checkout clone URL. No separate config to maintain (honors $MR_CONFIG).

2. projects.yaml — fallback when no .mrconfig is found. Checked at:

   • $XDG_CONFIG_HOME/ghud/projects.yaml (default: ~/.config/ghud/projects.yaml)
   • ~/Projects/pages/src/_data/projects.yaml

   The YAML uses a nested category/subcategory/project structure. Repos in the ignored category are excluded from the dashboard.

When the source is .mrconfig, ghud discover reports untracked repos but prints mr register hints instead of writing (myrepos owns that file).

Focused repos vs. the full manifest

A .mrconfig typically lists more than your own work — clones of upstream projects, forks you track locally, etc. By default ghud shows a focused set so those don't flood your dashboard:

• Repos you own (the owner/ matches your gh login) are shown by default.
• To pull a non-owned repo into the focused set, add ghud = track to its stanza.
• To mute one of your own repos, add ghud = ignore.

[Projects/cockpit-file-sharing]      # external — opt in
checkout = git clone https://github.com/45Drives/cockpit-file-sharing.git cockpit-file-sharing
skip = lazy
ghud = track

[Projects/old-thing]                 # owned but noisy — opt out
checkout = git clone [e-mail]:you/old-thing.git old-thing
skip = lazy
ghud = ignore

mr ignores the unknown ghud key. Use ghud --all-repos (also on ghud overview and ghud issue) to override and use the entire manifest. The projects.yaml equivalent of focus is its ignored category.

Features

Multi-View CLI

Browse issues, PRs, and repos with detail levels from brief (one-line summary) to full (body, all comments, timeline events, expanded CI checks).

Check Status Indicators

PR views show CI and review status at a glance: ✓ passing, ✗ failing, ● pending, — no checks.

Auto Repo Detection

When run inside a git repo, ghud detects the repo from your origin remote. Override with --repo or use --repo all for cross-repo views.

Responsive Layout

On wide terminals (>=120 columns), the dashboard uses a two-column layout. Narrow terminals get a single-column stack.

MCP Server

ghud serve starts an MCP server exposing dashboard tools for AI agents, enabling integration with tools like Claude Code.

Performance

ghud fetches all data in ~2 seconds using concurrent API calls and GraphQL batching for per-repo issue queries.

Development

git clone https://github.com/teaguesterling/ghud.git
cd ghud
pip install -e ".[dev]"
pytest

License

MIT