API Reference

CLI

CLI entry point using Typer.

class ghud.cli.AliasGroup(*, name: str | None = None, commands: dict[str, Command] | Sequence[Command] | None = None, rich_markup_mode: Literal['markdown', 'rich', None] = 'rich', rich_help_panel: str | None = None, suggest_commands: bool = True, **attrs: Any)

Typer group that supports command aliases.

get_command(ctx, cmd_name)

Given a context and a command name, this returns a Command object if it exists or returns None.

class ghud.cli.DetailLevel(*values)
class ghud.cli.IssueState(*values)
ghud.cli.default(ctx: Context, show_all: bool = <typer.models.OptionInfo object>, days: int = <typer.models.OptionInfo object>, all_repos: bool = <typer.models.OptionInfo object>)

GitHub Heads-Up Display.

ghud.cli.discover(dry_run: bool = <typer.models.OptionInfo object>)

Discover new repos not yet in projects.yaml.

ghud.cli.issue(number: int | None = <typer.models.ArgumentInfo object>, repo: str | None = <typer.models.OptionInfo object>, detail: DetailLevel = <typer.models.OptionInfo object>, comments: str = <typer.models.OptionInfo object>, state: IssueState = <typer.models.OptionInfo object>, limit: int = <typer.models.OptionInfo object>, no_pager: bool = <typer.models.OptionInfo object>, all_repos: bool = <typer.models.OptionInfo object>)

View issues. Without a number, lists issues. With a number, shows detail.

ghud.cli.main()

Entry point for the ghud CLI.

ghud.cli.overview(show_all: bool = <typer.models.OptionInfo object>, days: int = <typer.models.OptionInfo object>, all_repos: bool = <typer.models.OptionInfo object>)

Global dashboard — notifications, PRs, issues across portfolio repos.

ghud.cli.pr(number: int | None = <typer.models.ArgumentInfo object>, repo: str | None = <typer.models.OptionInfo object>, detail: DetailLevel = <typer.models.OptionInfo object>, comments: str = <typer.models.OptionInfo object>, state: IssueState = <typer.models.OptionInfo object>, limit: int = <typer.models.OptionInfo object>, no_pager: bool = <typer.models.OptionInfo object>)

View pull requests. Without a number, lists PRs. With a number, shows detail.

ghud.cli.repo(repo_flag: str | None = <typer.models.OptionInfo object>, no_pager: bool = <typer.models.OptionInfo object>)

Repo-level dashboard — issues, PRs, and activity for one repo.

ghud.cli.run_dashboard(show_all: bool = False, days: int = 7, all_repos: bool = False) → None

Run the overview dashboard (existing behavior).

ghud.cli.run_discover_cmd(dry_run: bool = False) → None

Run the discover command.

ghud.cli.run_issue_detail(repo: str, number: int, detail: str = 'standard', comments: str = '3', no_pager: bool = False) → None

Fetch and render issue detail.

ghud.cli.run_issue_list(repo: str | None = None, state: str = 'open', limit: int = 30, no_pager: bool = False, all_repos: bool = False) → None

Fetch and render the issue list.

ghud.cli.run_pr_detail(repo: str, number: int, detail: str = 'standard', comments: str = '3', no_pager: bool = False) → None

Fetch and render PR detail.

ghud.cli.run_pr_list(repo: str | None = None, state: str = 'open', limit: int = 30, no_pager: bool = False) → None

Fetch and render the PR list.

ghud.cli.run_repo_dashboard(repo: str | None = None, no_pager: bool = False) → None

Fetch and render the repo dashboard.

ghud.cli.run_serve() → None

Run the MCP server.

ghud.cli.serve()

Run MCP server (stdio).

Configuration

Resolve the portfolio repo list, from ~/.mrconfig or projects.yaml.

ghud.config.find_yaml_path(candidates: list[str] | None = None) → str | None

Return the first existing candidate path, or None.

ghud.config.load_repos_from_yaml(yaml_path: str, include_ignored: bool = False) → list[str]

Extract repo identifiers from projects.yaml.

Skips the ‘ignored’ category unless include_ignored is set. Handles both nested (subcategories -> projects) and flat (projects) layouts. Skips projects that have no ‘repo’ field (e.g. academic projects with only ‘url’).

ghud.config.resolve_portfolio(prefer_mrconfig: bool = True, focused: bool = True, username: str | None = None) → tuple[list[str], str | None]

Return (repos, source_path) for the portfolio.

Prefers a myrepos ~/.mrconfig manifest when present (it’s the version-controlled source of truth that mr already maintains), and falls back to projects.yaml. repos is a list of ‘owner/repo’ identifiers; source_path is the file they came from, or None if neither was found.

When focused (the default), the listing is narrowed to the repos you actually want to watch: from .mrconfig that’s repos you own plus any tagged ghud = track; from projects.yaml it’s everything outside the ignored category. Pass focused=False for the full manifest. For .mrconfig focusing, username is your GitHub login; if omitted it’s looked up via gh.

GitHub API

Wrapper around gh CLI for GitHub API access.

ghud.github.get_issue_detail(repo: str, number: int) → dict

Get detailed information for a single issue including comments.

ghud.github.get_issues_for_repo(repo: str, exclude_author: str = '') → list[dict]

Get open issues for a repo, optionally excluding an author.

ghud.github.get_issues_for_repos_batch(repos: list[str], exclude_author: str = '') → list[dict]

Fetch open issues for all repos in a single GraphQL query.

Batches repos into groups of 25 (GraphQL complexity limit) and returns a flat list of issues, each with a ‘repo’ field added.

ghud.github.get_merged_prs(username: str, days: int = 7) → list[dict]

Get PRs merged by the user within the lookback window.

ghud.github.get_notifications() → list[dict]

Get all unread notifications.

ghud.github.get_open_prs(username: str) → list[dict]

Get open PRs authored by the user.

ghud.github.get_pr_detail(repo: str, number: int) → dict

Get detailed information for a single PR including comments, reviews, and checks.

ghud.github.get_prs_for_repo(repo: str, state: str = 'open', limit: int = 30) → list[dict]

Get PRs for a repo with state filter.

ghud.github.get_username() → str

Get the authenticated GitHub username.

Data Processing

Shared data-fetching and filtering logic.

ghud.data.collect_other_activity(notifications: list[dict], portfolio_repos: set[str]) → tuple[list[dict], list[dict]]

Split notifications into portfolio and other activity.

Returns (portfolio_notifications, other_activity_summary).

ghud.data.fetch_dashboard_data(repos: list[str], username: str, days: int = 7) → dict

Fetch all dashboard data concurrently. Returns data dict.

ghud.data.filter_important_notifications(notifications: list[dict], important_only: bool = True) → list[dict]

Filter notifications to important ones only.

Dashboard Rendering

Terminal dashboard rendering with rich.

ghud.dashboard.render_dashboard(data: dict, console: Console | None = None, show_all: bool = False) → None

Render the full dashboard.

ghud.dashboard.render_dashboard_markdown(data: dict, show_all: bool = False) → str

Render the dashboard as a markdown string.

Issue Rendering

Issue rendering — list and detail views.

ghud.render_issue.render_issue_detail(issue: dict, repo: str, detail: str = 'standard', max_comments: int = 3, console: Console | None = None) → None

Render a detailed issue view.

Parameters:

  • issue – Issue dict from get_issue_detail.

  • repo – Repository identifier (owner/repo).

  • detail – One of ‘brief’, ‘summary’, ‘standard’, ‘full’.

  • max_comments – Max comments to show (ignored for ‘full’ which shows all).

  • console – Rich Console.

ghud.render_issue.render_issue_list(issues: list[dict], repo: str | None = None, console: Console | None = None) → None

Render a table of issues.

Parameters:

  • issues – List of issue dicts.

  • repo – If set, single-repo mode (no repo column). If None, cross-repo mode.

  • console – Rich Console. Created if not provided.

PR Rendering

PR rendering — list and detail views.

ghud.render_pr.render_pr_detail(pr: dict, repo: str, detail: str = 'standard', max_comments: int = 3, console: Console | None = None) → None

Render a detailed PR view.

ghud.render_pr.render_pr_list(prs: list[dict], repo: str | None = None, console: Console | None = None) → None

Render a table of PRs.

Repo Rendering

Repo-level dashboard rendering.

ghud.render_repo.render_repo_dashboard(data: dict, repo: str, console: Console | None = None) → None

Render a repo-level dashboard with issues and PRs summary.

Repo Context

Git remote detection and –repo flag resolution.

ghud.repo_context.resolve_repo(repo_flag: str | None = None) → str | None

Resolve the target repo.

Returns owner/repo string, or None for cross-repo mode. - If repo_flag is provided and not “all”, use it directly. - If repo_flag is “all”, return None (cross-repo). - Otherwise, detect from git remote. Returns None if not in a git repo.

Pager

Pager utility for Rich console output.

ghud.pager.render_with_pager(render_fn: Callable[[Console], None], console: Console | None = None, no_pager: bool = False) → None

Render content, optionally wrapping in a pager.

Only pages if output exceeds the terminal height. Uses LESS=-R to ensure ANSI color codes are interpreted correctly.

Parameters:

  • render_fn – Function that takes a Console and prints to it.

  • console – Rich Console instance. Created if not provided.

  • no_pager – If True, render directly without pager.

Discovery

Repo discovery: find GitHub repos not yet in projects.yaml.

ghud.discover.fetch_all_user_repos(username: str) → list[dict]

Fetch all repos the user owns or collaborates on.

ghud.discover.find_new_repos(github_repos: list[dict], known_repos: list[str]) → list[dict]

Find repos present on GitHub but not in projects.yaml.

ghud.discover.format_new_project(repo: dict) → dict

Format a GitHub repo as a projects.yaml project entry.

ghud.discover.run_discover(args: Namespace) → None

Run the discover command.

MCP Server

MCP server exposing ghud tools for AI agents.

ghud.mcp.discover_repos() → list[dict]

Find GitHub repos not yet tracked in projects.yaml.

Returns a list of repos with nameWithOwner, name, description, and fork status. Does not modify projects.yaml.

ghud.mcp.get_dashboard(show_all: bool = False, days: int = 7) → str

Get the full GitHub dashboard as formatted markdown.

Shows notifications, open PRs, recently merged PRs, issues from others, and other activity across portfolio repos.

ghud.mcp.get_issues_from_others() → list[dict]

Get open issues on portfolio repos created by other people.

Excludes issues you authored. Returns issues with repo, title, author, createdAt, url, labels.

ghud.mcp.get_merged_prs_tool(days: int = 7) → list[dict]

Get your recently merged pull requests.

Returns PRs merged within the lookback window (default 7 days).

ghud.mcp.get_notifications_tool(important_only: bool = True) → list[dict]

Get GitHub notifications for portfolio repos.

By default returns only important notifications (review_requested, mention, assign, team_mention, security_alert). Set important_only=False for all.

ghud.mcp.get_open_prs_tool() → list[dict]

Get your open pull requests across all repos.

Returns raw API fields: title, repository, state, createdAt, updatedAt, url, commentsCount.

ghud.mcp.get_portfolio_repos() → list[str]

Get the list of portfolio repos from projects.yaml.

ghud.mcp.main()

Entry point for ghud-mcp script.