ghr

ghr is a fast terminal workspace for staying on top of GitHub. It brings your GitHub inbox, pull requests, issues, repo tabs, conversations, checks, and diffs into one stateful TUI, so you can triage, review, comment, approve, merge, and jump back in without waiting on a fresh GitHub fetch.

Conversation and triage view

Pull request diff review view

Features

• Inbox, pull request, and issue views.
• Snapshot-first startup: cached data is shown immediately, the active view refreshes first, and non-active PR/issue sections are kept warm by a quiet idle sweep.
• Configurable sections and repo tabs, including multi-query sections such as Needs Attention.
• Automatic current-repo tab persistence when launched inside a Git checkout with a GitHub remote.
• Paged PR and issue lists with configurable page size.
• Persistent ignored PRs and issues, stored in UI state and hidden from all lists.
• Recent Items command for jumping back to the last 200 PRs and issues, including linked inbox notifications, where you spent at least 10 seconds in Details.
• Fuzzy filtering in every loaded list with /, quick PR/issue section filters with f, plus repo-scoped GitHub search with S.
• Details pane with rendered Markdown, clickable links and image attachments, fenced code blocks with lightweight Rust and plain/log highlighting, descriptions, comments, review comments, PR commit activity, labels, milestones, action hints, and check summaries.
• Inbox notifications lazily load linked PR or issue details when opened, so descriptions and recent PR commit activity appear without making the initial inbox fetch heavier.
• PR diff mode with a changed-file list, per-file diff rendering, inline review comments, and review ranges.
• Comment, reply, edit, milestone, merge, close/reopen, update-branch, rerun-failed-checks, local PR checkout, draft / ready-for-review, and full PR review submit flows from inside the TUI.
• Inbox read/done/mute handling with explicit commands, local cache updates, GitHub sync, and dimmed read items.
• Mouse support for tabs, lists, links, descriptions, comments, editor cursor placement, details drag-copy, scrolling, text selection mode, and split resizing.
• Built-in dark and light themes configured through defaults.theme.
• UI state persistence under ~/.ghr, including focus, selected item, scroll position, split ratio, and diff mode.
• Local state under ~/.ghr: config, SQLite snapshot database, logs, and UI state.
• Uses the GitHub CLI for authentication, API access, and browser opening behavior.

Requirements

• GitHub CLI gh
• An authenticated GitHub CLI session:

gh auth login

Installation

You can install ghr with Cargo:

cargo install ghr-cli

Or install the latest release binary on macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/chenyukang/ghr/main/install.sh | sh

Install the latest release binary on Windows PowerShell:

irm https://raw.githubusercontent.com/chenyukang/ghr/main/install.ps1 | iex

Then authenticate GitHub CLI and run ghr:

gh auth login
ghr

## by default, ghr starts in the Inbox/Issues/Pull Requests view
## go to some dir with a GitHub remote and run ghr to see the repo tab show up
## command palette (press `:`) and then type "Project Add" to add new repos

The installers detect your OS and CPU architecture, download the matching GitHub release asset with visible progress, verify its .sha256, and install ghr into ~/.local/bin by default. Use GHR_INSTALL_DIR to choose another install directory, or GHR_VERSION to pin a release tag:

curl -fsSL https://raw.githubusercontent.com/chenyukang/ghr/main/install.sh | GHR_VERSION=v0.7.2 GHR_INSTALL_DIR=/usr/local/bin sh

Usage

Run ghr from any terminal after gh auth login. When started inside a Git checkout with a GitHub remote, ghr adds that repository as a local project tab automatically.

Keybindings

Press ? in the TUI for the live shortcut reference. The top-right status shows the current app state; the footer stays focused on the most useful shortcuts for the active area.

Diff review ranges:

• Press m on a diff line to begin a range, move the highlight, then press e to end it.
• Press c after ending a range to post an inline review comment for the selected range.
• With the mouse, single click selects one diff line. Double click begins a range, then single click the end line to complete it.
• Press s to open the review summary editor, use Tab or 1 / 2 / 3 to choose comment, request changes, or approve, then press Ctrl+Enter to submit.
• Press Ctrl+P in the review summary editor to create a pending review draft, then press s later to submit it or D to discard it.

Local PR checkout:

• Press X on a pull request in the list or Details pane, then confirm with y or Enter.
• Pull request Details show the remote branch as a clickable link when GitHub provides it.
• Checkout runs from the matching local repository directory. Set local_dir on a repo entry to make the target explicit:

[[repos]]
name = "Rust"
repo = "rust-lang/rust"
local_dir = "~/code/rust"
show_prs = true
show_issues = true

• If local_dir is not set, ghr tries the directory where it was launched when that directory has a GitHub remote for the pull request repository. If neither path matches, ghr shows a hint instead of running checkout.

Mouse behavior:

• Click ghr or Sections tabs to switch views or sections.
• Click list rows to select them and focus Details. Mouse hover and mouse wheel do not change PR/issue selection.
• Click descriptions, comments, links, and visible actions in Details to focus or open them.
• Click inside comment, review, issue, or PR editor dialogs to place the edit cursor.
• Drag text inside Details to copy that rendered selection to the clipboard without leaving mouse mode.
• Scroll Details with the mouse wheel.
• Drag the split between list and Details to resize panes; the ratio is saved.
• Press m outside diff mode to temporarily disable TUI mouse capture for terminal text selection; press m again to restore mouse controls.

Default Sections

Inbox:

• All
• Review Requested
• Assigned
• Mentioned
• Subscribed
• Others

Pull Requests:

• Needs Attention: open PRs where you were requested for review, assigned, or mentioned.
• My Pull Requests: open PRs authored by you.
• Reviewed: open PRs reviewed by you and authored by someone else.

Issues:

• Assigned to Me
• Mentioned
• Involved

Configuration

The config file is created at:

~/.ghr/config.toml

Example:

[[repos]]
name = "Rust"
repo = "rust-lang/rust"
show_prs = true
show_issues = true
labels = ["T-compiler"]
pr_labels = ["S-waiting-on-review"]
issue_labels = ["E-easy"]

[defaults]
view = "pull_requests"
command_palette_key = ":"
theme = "dark"
log_level = "info"
pr_per_page = 50
issue_per_page = 50
notification_limit = 50
refetch_interval_seconds = 60
include_read_notifications = true

[[pr_sections]]
title = "Needs Attention"
queries = [
  "is:open review-requested:@me archived:false sort:updated-desc",
  "is:open assignee:@me archived:false sort:updated-desc",
  "is:open mentions:@me archived:false sort:updated-desc",
]

[[pr_sections]]
title = "My Pull Requests"
filters = "is:open author:@me archived:false sort:updated-desc"

[[pr_sections]]
title = "Reviewed"
filters = "is:open reviewed-by:@me -author:@me archived:false sort:updated-desc"

exclude_repos = ["some-org/archive-*"]

Use filters for a single GitHub search query. Use queries when a section should merge several GitHub searches into one deduplicated list. Label filters can be written directly in either form, for example filters = "is:open label:bug archived:false sort:updated-desc" or label:"good first issue" for labels with spaces.

Use [[repos]] to add repository tabs to the top bar. Each configured repo shows its name as a top-level tab; inside that tab, show_issues and show_prs control whether the sections are shown as Issues and Pull Requests. Repo tabs default to open issues and open PRs, with Issues shown first. Set labels to filter both repo issue and PR lists, or use issue_labels / pr_labels for kind-specific filters.

When ghr starts inside a Git checkout with a GitHub remote, it adds that repository as a repo tab if it is not already configured and saves it back to config.toml with local_dir set to the launch directory. If the repo already exists in the config but has no local_dir, ghr fills that field without overwriting an existing value.

Set command_palette_key to change the command palette shortcut. Printable keys such as ":" are treated as text while typing in search, filter, and editor dialogs; use a modified key such as "Ctrl+L" if you want the palette to open from those text inputs.

Set theme to "dark" or "light" to switch the TUI palette.

Set log_level to trace, debug, info, warn, or error. In debug mode, gh / gh api requests plus UI focus/view changes and mouse clicks are written to ~/.ghr/ghr.log. RUST_LOG still overrides this config value when it is set.

pr_per_page and issue_per_page control the page size used for PR and issue search sections. Use [ and ] in the list to load adjacent GitHub result pages.

Local Data

ghr keeps all local files in ~/.ghr:

• config.toml: user configuration
• ghr.db: SQLite snapshot cache
• ghr.log: log file
• state.toml: persisted UI state, including ignored PRs/issues

The snapshot cache is intentionally local and disposable. Use the Clear Cache command to clear one cache layer, or delete ~/.ghr/ghr.db if you want to rebuild every persisted cache row from GitHub.

Contributing

Contributions are very welcome! Please open an issue or a pull request with any bug fixes, improvements, or new features.