ghui

Terminal UI for keeping up with GitHub pull requests, issues, diffs, and Actions across repositories.

ghui gives you one keyboard-driven place to review PR details, inspect diffs, monitor and control Actions, 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 phall1/tap/ghui

Upgrade with:

brew upgrade ghui

This fork publishes standalone binaries from phall1/ghui and updates the phall1/tap formula automatically. It does not publish the upstream npm package. The upstream npm release remains available separately:

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/phall1/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 or repository Actions view, 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

Open a repository and select its Actions tab to monitor recent workflow runs across branches and events. Active runs refresh automatically while the surface is visible. You can also press a on a pull request to open runs scoped to that PR's head commit.

• The runs list shows each workflow, branch, 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, o opens the run in your browser, and r refreshes.
• R reruns a completed workflow, F reruns failed jobs, and x cancels an active run.
• tab / shift-tab move between repository surfaces; esc walks back through run detail and repository scope.

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
• 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.