ghspot

command module
v0.0.0-...-699c1c4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 24 Imported by: 0

README ΒΆ

ghspot

Spotlight for your GitHub issues and pull requests.

Fuzzy-find any ticket by title or number, read it right in your terminal,
and open it in the browser only when you actually want to.

Go Built with Bubble Tea

ghspot demo

Why

gh issue list | grep gets old fast, and the GitHub web search is a context switch. ghspot loads your repo's tickets in the background and filters them as fast as you can type, the same way Spotlight or Raycast does. Results show up instantly, previews render as proper Markdown, and the browser stays shut until you ask for it.

Features

  • ⚑ Instant fuzzy search. Type words in any order, with typos. Literal and word-start matches rank first, and matched letters are highlighted.
  • πŸ”’ Jump by number. 123 or #123 puts that ticket on top. If it isn't cached yet, it's fetched straight from GitHub.
  • πŸ—‚ Scope to a repo with one word. When searching across repos, start with part of a repo name: glamour table, api 512, or just api.
  • πŸ“– Read in the app. A live side preview, plus a full-screen reader with rendered Markdown, labels, PR branches and diff stats, review state and comments.
  • 🌐 Browser on demand. ctrl+o from the list or o in the reader. Nothing opens unless you ask.
  • πŸŽ› Filters. tab cycles All / Issues / PRs and ctrl+s cycles Open / Closed / Any.
  • πŸ”­ Not limited to the cache. Open and closed tickets load in parallel, and every query also searches GitHub in the background, so old tickets still turn up.
  • πŸ” No extra setup. Authentication reuses your existing gh login.

Screenshots

Fuzzy search with live preview

Fuzzy search with live preview

Full-screen reader

Full-screen reader

Jump to any number

Jump to #42, fetched from GitHub on demand

Scope to a repo with one word

glamour table, scoped to one repo in an org

Filters

Closed issues only, with comments in the preview

Install

You need the GitHub CLI logged in (gh auth login).

curl -fsSL https://raw.githubusercontent.com/jaderfeijo/ghspot/main/install.sh | bash

(builds it with Go into ~/.local/bin; ... | bash -s -- --uninstall removes it). It works on macOS, Linux (any distro) and the BSDs, and needs only bash and Go; make sure ~/.local/bin is on your PATH. Or with Go directly:

go install github.com/jaderfeijo/ghspot@latest

Or build from source:

git clone https://github.com/jaderfeijo/ghspot && cd ghspot
go build -o ~/.local/bin/ghspot .

[!TIP] Status icons use Nerd Font glyphs. No Nerd Font? Run with --no-icons.

Usage

ghspot                    # the repo you're in (or everything involving you, outside a repo)
ghspot -R cli/cli         # any repo
ghspot --org charmbracelet  # every repo in an org
ghspot --mine             # everything involving you, across GitHub
ghspot -1 flaky test      # start with a query; quit after opening in the browser
You type You get
login bug titles containing both words, in any order, typos allowed
#512 or 512 ticket 512 first, then numbers starting with 512
api 512 ticket 512 in the repo whose name starts with api (multi-repo scopes)
api timeout titles matching timeout, only in that repo
Keys

List

Key Action
↑ ↓ Β· ctrl+p ctrl+n move (ctrl+b / ctrl+f page)
enter read the ticket full-screen
ctrl+o open in browser (alt+enter: open and quit)
tab All β†’ Issues β†’ PRs
ctrl+s Β· shift+tab Open β†’ Closed β†’ Any state
ctrl+y copy URL
pgup pgdn Β· shift+↑↓ Β· mouse wheel scroll preview
ctrl+t toggle preview
ctrl+r reload
esc clear the query, then quit

Reader

Key Action
esc Β· q back to the list
o open in browser (O: open and quit)
y copy URL
j k Β· space b Β· g G scroll, page, top / bottom
n p next / previous result

The browser is $BROWSER if set, otherwise open on macOS and xdg-open on Linux. Copying uses pbcopy on macOS, wl-copy on Wayland and xclip on X11.

Tip: bind it to a hotkey

ghspot works well as a launcher: a hotkey opens a floating terminal, you find the ticket, and alt+enter opens it and closes the window. With Hyprland, for example:

bind = SUPER, G, exec, foot --app-id=ghspot -e ghspot -1 -R your/repo
windowrule = float, class:^(ghspot)$
windowrule = size 70% 70%, class:^(ghspot)$

How it works

  • Tickets come from GitHub's GraphQL search API through go-gh, with the token from gh. ghspot never stores credentials.
  • On start it pages through the 1,000 most recently updated open tickets and the 1,000 most recent closed ones, newest first, while you're already typing.
  • Each query is matched locally, so results appear instantly. After a short pause ghspot also asks GitHub, merges in whatever wasn't cached, and looks up unknown numbers directly.
  • Built with Bubble Tea, Lip Gloss and Glamour.

The demo is recorded with VHS. Run vhs demo.tape to regenerate it.

License

MIT Β© Jader Feijo

Documentation ΒΆ

The Go Gopher

There is no documentation for this package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL