# gh-threads

A read-only terminal UI for people receiving GitHub pull-request reviews. It
shows open PRs, review threads with highlighted diff hunks and comment authors,
reviewer/assignee state, and the latest commit's check rollup. Resolved threads
start folded. GitHub suggestion blocks are shown as syntax-highlighted
remove/add previews. Comments 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" or "light"
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

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

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`, `--path-scroll`, and `--path-scroll-interval`. Boolean
settings can be disabled explicitly, for example `--path-scroll=false`.

## Keys

| Key | Action |
| --- | --- |
| `h` / `l` | Focus the thread list / thread detail |
| `j` / `k` | Move between threads or scroll the focused detail |
| `?` | Show contextual keybinding help |
| `/` | Fuzzy-search thread file paths |
| `↑` / `↓` | Choose a fuzzy-search match |
| `g` / `G` | First / last item |
| `enter` / `l` | Open a PR |
| `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 PR picker |
| `r` | Refresh now |
| `q` | Quit |

## Current scope

The application is intentionally read-only. GitHub's GraphQL API currently
limits this client to the first 100 review threads and first 100 comments per
thread; the UI warns when the thread list is truncated. GitHub features which
depend on server-side context, such as unfurling issue references or displaying
uploaded images, are represented textually in the terminal.