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.
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.
123or#123puts 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 justapi. - π 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+ofrom the list oroin the reader. Nothing opens unless you ask. - π Filters.
tabcycles All / Issues / PRs andctrl+scycles 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
ghlogin.
Screenshots

Fuzzy search with live preview

Full-screen reader

Jump to #42, fetched from GitHub on demand

glamour table, scoped to one repo in an org

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
Search
| 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
ΒΆ
There is no documentation for this package.