Usage

Overview Dashboard

# Show your dashboard (default)
ghud

# Explicit overview command
ghud overview

# Include low-priority notifications (subscribed, comment, etc.)
ghud overview --all

# Extend merged-PR lookback to 30 days
ghud overview --days 30

The dashboard shows five sections (empty sections are hidden):

  1. Important Notifications — review_requested, mention, assign, team_mention, security_alert

  2. New Issues From Others — open issues on your portfolio repos, excluding your own

  3. Your Open PRs — PRs you authored, with age and comment counts

  4. Recently Merged — your PRs merged within the lookback window

  5. Other Activity — notifications from repos not in your portfolio

On wide terminals (>=120 columns), sections are arranged in two columns: attention-needed on the left, your activity on the right.

Issues

# List open issues for the current repo (detected from git remote)
ghud issue
ghud i

# List issues for a specific repo
ghud i --repo owner/repo

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

# View issue detail
ghud i 42

# View with different detail levels
ghud i 42 --detail brief      # Header + comment count only
ghud i 42 --detail summary    # Header + all comment headers (no bodies)
ghud i 42 --detail standard   # Header + body + last 3 comments (default)
ghud i 42 --detail full       # Everything including timeline events

# Control comment display
ghud i 42 --comments 10       # Show last 10 comments
ghud i 42 --comments all      # Show all comments

# Filter and limit list view
ghud i --state closed
ghud i --limit 50

Pull Requests

# List open PRs for the current repo
ghud pr

# List PRs for a specific repo
ghud pr --repo owner/repo

# View PR detail
ghud pr 15

# View with different detail levels
ghud pr 15 --detail brief      # Header only
ghud pr 15 --detail standard   # Header + body + comments + check indicator
ghud pr 15 --detail full       # All of the above + expanded checks + reviews

PR list views show check status indicators:

  • ✓ — all checks passing

  • ✗ — one or more checks failing

  • ● — checks pending

  • — — no checks configured

Repo Dashboard

# Dashboard for the current repo
ghud repo
ghud r

# Dashboard for a specific repo
ghud r --repo owner/repo

Shows open issues and pull requests for a single repo in a combined view.

Discover

# See what repos are missing from your portfolio config
ghud discover --dry-run

# Add missing repos to the 'uncategorized' section
ghud discover

The discover command queries your GitHub account for all repos and compares against your portfolio. With a projects.yaml portfolio, new repos are added to an uncategorized section for you to organize later. When your portfolio comes from ~/.mrconfig, discover instead prints mr register hints (myrepos owns that file) rather than writing.

MCP Server

ghud serve

Starts an MCP (Model Context Protocol) server over stdio, exposing dashboard tools for AI agents. Available tools include get_dashboard, get_notifications_tool, get_open_prs_tool, get_merged_prs_tool, get_issues_from_others, get_portfolio_repos, and discover_repos.

Common Options

--repo / -r

Specify a repository as owner/repo. Use --repo all to operate across all portfolio repos. If omitted, ghud detects the repo from your current git directory’s remote.

--no-pager

Disable piping output through a pager. By default, detail views use a pager when output exceeds the terminal height.

Subcommand Aliases

For quick access:

  • ghud i → ghud issue

  • ghud o → ghud overview

  • ghud r → ghud repo

Configuration

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

  1. ~/.mrconfig — if you manage your repos with myrepos (mr), ghud reads its manifest directly, deriving 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 categories -> subcategories -> projects structure. Repos in the ignored category are excluded from the dashboard.

Focused repos vs. the full manifest

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

  • Repos you own (owner/ matches your gh login) are shown by default.

  • Add ghud = track to a stanza to pull a non-owned repo into the focused set.

  • Add ghud = ignore to mute one of your own repos.

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