# gh-threads

A read-only terminal UI for people receiving GitHub pull-request reviews. It
shows open PRs and a scrollable PR dashboard with the description, branches,
review state, checks, people, labels, milestone, activity, change statistics,
thread totals, submitted reviews, and the PR conversation. Review threads and
comments are paginated rather than silently stopping at the first page. The
thread viewer includes highlighted diff hunks and comment authors. Resolved
threads start folded. GitHub suggestion blocks are shown as
syntax-highlighted remove/add previews. Comments and PR descriptions render
GitHub Flavored Markdown, including quoted replies, inline and fenced code,
lists and tasks, links, tables, emphasis, strikethrough, emoji, and GitHub
alerts. The current PR is refreshed in the background.

## Install and run

Requires Go 1.24+ and an authenticated GitHub CLI:

```sh
go install .
gh auth login
gh-threads
```

To run directly from a source checkout instead:

```sh
go run .
```

Use `go run .`, not `go run main.go`: the latter compiles only `main.go` and
omits the other files in the package.

For automation, `GH_TOKEN` or `GITHUB_TOKEN` can still be provided and takes
precedence over the GitHub CLI credential. Enterprise token environment
variables are also supported.

By default the PR picker searches all repositories for open PRs assigned to the
authenticated user and groups the results by repository. Use `--repo` to limit
the picker to one repository:

```sh
gh-threads --repo owner/repository
```

With a repository selected, pass `--all` to include every open PR in that
repository:

```sh
gh-threads --repo owner/repository --all --poll 15s
```

GitHub Enterprise Server can be used after authenticating that host:

```sh
gh auth login --hostname github.example.com
gh-threads --repo owner/repository \
  --endpoint https://github.example.com/api/graphql
```

## Configuration

The optional TOML configuration is loaded from
`$GH_THREADS_CONFIG`, `$XDG_CONFIG_HOME/gh-threads/config.toml`, or the
operating system's user configuration directory at `gh-threads/config.toml`.
On Linux this is normally `~/.config/gh-threads/config.toml`. On macOS,
`~/Library/Application Support/gh-threads/config.toml` is preferred, with
`~/.config/gh-threads/config.toml` automatically used as a fallback when it
exists.

```toml
theme = "dark"                 # dark, light, high-contrast, or no-color
refresh_interval = "10s"
repository = ""               # optional owner/repository default
show_all = false              # requires repository
limit = 50
endpoint = "https://api.github.com/graphql"

[display]
fold_resolved = true
thread_list_width_percent = 33 # 20-60
dashboard_mode = "hotkey"      # "hotkey" or "intermediate"
compact_reviews = true         # aggregate submitted review history

[paths]
scroll = false
scroll_interval = "350ms"      # minimum 50ms

[threads]
# Each status must occur exactly once. "outdated" means unresolved and outdated;
# resolved threads remain in "resolved" even when they are also outdated.
status_order = ["unresolved", "outdated", "resolved"]
within_status = "file"          # "file" or "timestamp" (oldest first)

[cache]
enabled = true                 # instant stale view plus offline fallback
max_age = "168h"               # 7 days; 0 means no age limit
directory = ""                 # defaults to the OS user cache directory
```

When cached data exists, the picker and PR details are rendered immediately
from that snapshot while a live GitHub refresh runs in the background. Cached
screens are labelled with their save time and are replaced automatically when
fresh data arrives. Check annotations are fetched separately only for failed
checks so they do not inflate the initial PR query.

The cache uses separate JSON files for the picker and each visited PR. Cache
content is hashed before writing: unchanged responses do not rewrite their
files. Their modification time is touched at most once per day (or half the
configured maximum age, when shorter) so recently validated snapshots remain
usable without writing on every poll. Changed files are replaced atomically.

Command-line flags override the configuration. `GH_REPO` overrides the
configured repository when `--repo` is not provided. The corresponding flags
include `--config`, `--theme`, `--poll`, `--fold-resolved`,
`--thread-list-width`, `--dashboard-mode`, `--compact-reviews`,
`--path-scroll`, and `--path-scroll-interval`, plus `--cache`,
`--cache-max-age`, and `--cache-dir`.
Boolean settings can be disabled explicitly, for
example `--compact-reviews=false`.

With the default `dashboard_mode = "hotkey"`, opening a PR goes directly to its
review threads and `d` opens the dashboard only when requested. Set
`dashboard_mode = "intermediate"` to follow picker → dashboard → review
threads instead.

Compact reviews aggregate submission counts by state and author. Reviews with
a written summary retain a compact one-line body, while timestamps and commit
SHAs are omitted. Set `compact_reviews = false` to restore the complete review
history and metadata.

## Keys

| Key | Action |
| --- | --- |
| `h` / `l` | Focus the thread list / thread detail |
| `j` / `k` | Move between items or scroll the dashboard/focused detail |
| `?` | Show contextual keybinding help |
| `d` | Open the current pull request dashboard |
| `/` | Fuzzy-search paths and filter with `status:`, `author:`, `updated:true` |
| `F` | Clear active thread filters |
| `n` / `N` | Next / previous thread with a new update |
| `↑` / `↓` | Choose a fuzzy-search match |
| `g` / `G` | First / last item |
| `enter` / `l` | Open the selected PR dashboard or its review threads |
| `enter` | Toggle the selected review thread |
| `za` | Toggle the selected thread |
| `ctrl-d` / `ctrl-u` | Scroll thread detail or page through lists |
| `tab` | Hide or reveal the thread list |
| `b` / `esc` | Return to the previous screen |
| `r` | Refresh now |
| `q` | Quit |

## Current scope

The application is intentionally read-only. The dashboard and contextual help
show the write capability gate, including why each future write action is
unavailable. Read state persists beside the configuration, and recent PR data
is cached for offline fallback. Check contexts and annotations are paginated.
GitHub features which depend
on server-side context, such as unfurling issue references or displaying
uploaded images, are represented textually in the terminal. See
[`TODO.md`](TODO.md) for remaining read-only work and write-support preparation.