ghui

Terminal UI for keeping up with your open GitHub pull requests across repositories.

ghui gives you one keyboard-driven place to review PR details, inspect diffs, leave diff comments, manage labels, toggle draft state, merge, open PRs in GitHub, and copy PR metadata without leaving the terminal.

Install

Homebrew is the recommended install path on macOS and Linux. It installs a standalone ghui binary, so you do not need Bun or npm at runtime.

brew install kitlangton/tap/ghui

Upgrade with:

brew upgrade ghui

Or install with npm:

npm install -g @kitlangton/ghui

The npm package also installs a platform-specific binary package and does not require Bun.

Requirements:

• GitHub CLI installed and authenticated with gh auth login

Run it from anywhere:

ghui

Local Development

Clone, install, and link:

git clone https://github.com/kitlangton/ghui.git
cd ghui
bun install
bun link

With Nix flakes:

nix develop
bun install
bun run dev

Configuration

• GHUI_PR_FETCH_LIMIT: max PRs fetched, defaults to 200
• GHUI_RUN_FETCH_LIMIT: max workflow runs fetched per PR, defaults to 20

Example:

GHUI_PR_FETCH_LIMIT=100 ghui

You can also copy .env.example to .env and edit the values locally.

ghui stores UI preferences in config.json under GHUI_CONFIG_DIR when set, otherwise under the platform config directory. On Linux this is normally ~/.config/ghui/config.json.

Example:

{
    "theme": "system",
    "systemThemeAutoReload": true,
    "showScrollbars": false
}

systemThemeAutoReload defaults to false. Set it to true to let external theme reload signals update the active system theme palette while ghui is running.

Scrollable panes hide their scrollbar rails by default. Set showScrollbars to true to display them while retaining the same keyboard and mouse scrolling behavior.

Open in editor

Press e on a pull request (in the list, detail, or diff view) to hand it off to your editor. ghui suspends the TUI, runs your command attached to the terminal, and resumes when it exits.

Configure this in config.json:

{
    "editorCommand": "tmux new-window -c {{repoPath}} 'gh pr checkout {{number}} && nvim -c \":DiffviewOpen {{baseRef}}...{{headRef}}\"'",
    "repoPaths": {
        "kitlangton/ghui": "~/code/ghui",
        "kitlangton/*": "~/code/repos/kitlangton/*",
        ":owner/:repo": "~/src/github.com/:owner/:repo"
    }
}

repoPaths maps a repository to a local clone, matched in order: an exact owner/repo key, then an owner wildcard (owner/*, where * becomes the repo name), then the generic :owner/:repo template. ~ expands to your home directory.

editorCommand is a shell command template with these substitutions:

• {{repo}} — full owner/repo
• {{owner}}, {{name}}
• {{number}} — PR number
• {{headRef}} — PR head branch
• {{baseRef}} — base branch
• {{author}}
• {{url}}
• {{repoPath}} — resolved local path (requires a matching repoPaths entry)

If editorCommand is omitted, ghui falls back to $VISUAL/$EDITOR opening the resolved repoPath. Some common recipes:

// diffview.nvim: checkout the branch and diff against base
"editorCommand": "tmux new-window -c {{repoPath}} 'gh pr checkout {{number}} && nvim -c \":DiffviewOpen {{baseRef}}...{{headRef}}\"'"

// octo.nvim: review via the GitHub API (no checkout)
"editorCommand": "tmux new-window -c {{repoPath}} 'nvim -c \":silent Octo pr edit {{number}}\"'"

// VS Code
"editorCommand": "code {{repoPath}}"

Workflow runs

Press a on a pull request to open its GitHub Actions runs full-screen, scoped to the PR's head commit:

• The runs list shows each workflow run with status, conclusion, duration, and age.
• enter drills into a run to see its jobs and steps; failing steps are easy to spot.
• n / p jump between failures, enter expands a step, o opens the run in your browser, r refreshes, and esc walks back out.

Requires the GitHub CLI (gh) the same as the rest of ghui; nothing extra to configure.

Keybindings

• up / down: move selection
• k / j: move selection
• gg / G: jump to first or last pull request
• ctrl-u / ctrl-d: page up or down
• tab / shift-tab: switch PR queue
• ctrl-p / cmd-k: open the command palette
• /: filter
• enter: expand details; normal PR actions still work while details are expanded
• esc: return from expanded details, leave diff/comment mode, or close modal
• r: refresh
• d: view stacked diff for all changed files
• a: view this PR's GitHub Actions runs (jobs, steps, and failing logs)
• shift-r: review or approve the selected pull request
• up / down / pageup / pagedown: move comment target while viewing a diff
• enter: open a commented diff line, or start a comment on an uncommented line
• v: start or clear a multi-line diff comment range
• n / p: jump between diff comment threads
• f: open the changed-files navigator while viewing a diff
• left / right: choose the deleted or added side while in split diff comment mode
• [ / ]: switch files while viewing or commenting on a diff
• s: toggle draft or ready-for-review state
• m: merge
• x: close with confirmation
• t: choose a fixed theme, including System to match your terminal colors; press m in the theme picker to follow the OS light/dark appearance with separate theme choices
• l: manage labels
• o: open PR in browser
• e: open PR in your editor (configurable; see editorCommand / repoPaths)
• y: copy PR metadata
• q: quit

Authored-only pull request views render compact one-line rows because the author identity is implied by the active view. Mixed-author views continue to show the author and branch metadata row.

Review submission:

• Press shift-r to open the review modal.
• Use j / k or up / down to choose Comment, Approve, or Request changes.
• Press enter to move to the optional summary area.
• Press enter again to submit, or shift-enter to insert a newline.
• Press esc from the summary to return to action selection; press esc from action selection to cancel.