# ghzinga

`ghzinga` is a small terminal UI for keeping GitHub pull requests and issues
open on the side while you work.

It is not trying to be a full GitHub client. It is for maintainers who want a
faster-than-the-web-UI view of the current status, comments, checks, files, and
links for a PR or issue, with automatic refresh. It is similar in spirit to
[`gh dash`](https://github.com/dlvhdr/gh-dash), but focused on a single item
first instead of a dashboard list.

`ghzinga` is inspired by [`Herdr`](https://herdr.dev/) and built with
[`Ratatui`](https://ratatui.rs/) and
[`Crossterm`](https://github.com/crossterm-rs/crossterm), so the terminal UI is
interactive: click tabs and links, expand rows, scroll with the mouse wheel,
drag the scrollbar, or use keyboard shortcuts.



https://github.com/user-attachments/assets/1078941e-f83f-4d6f-aceb-695a22015580



## Install

Install from crates.io:

```sh
cargo install ghzinga
```

Install from a local checkout:

```sh
cargo install --path .
```

This installs two equivalent commands:

- `gzg`
- `ghzinga`

## Usage

Open a pull request or issue:

```sh
gzg openclaw/openclaw#81834
gzg https://github.com/openclaw/openclaw/pull/81834
gzg https://github.com/openclaw/openclaw/issues/88499
```

Run `gzg` again from the same terminal context to restore the last ghzinga
dashboard for that pane, tmux pane, Herdr pane, working tree, or named session.
Use `--new` to start a separate saved session, `--no-restore` to ignore saved
state for one run, or `--session <name>` to pick a specific saved session.

`ghzinga` reuses your existing GitHub CLI login through `gh auth token`. You can
also set `GH_TOKEN` or `GITHUB_TOKEN` to override that token. Public repositories
can fall back to unauthenticated GitHub data when credentials are unavailable.

## What You Get

For pull requests, ghzinga shows:

- overview and conversation
- author, labels, branches, review state, and merge/check status
- activity, reviews, review comments, and linked issues or PRs
- commits
- checks and status contexts
- changed files with expandable patch context

For issues, ghzinga shows:

- overview and conversation
- author, labels, assignees, state, milestones, and projects
- timeline activity and comments
- linked issues or PRs

## Interaction

The UI is built for active terminal use:

- click tabs to switch views
- click the top-right plus button, or press `n`, to open another PR or issue
- when multiple resources are open, click the resource tabs to switch or close them
- click GitHub issue/PR links to choose between opening here or in a new tab
- click same-resource comment links to focus the matching Activity entry
- click rows and `[more]` controls to expand details
- click footer actions for refresh, expand/collapse, settings, help, and quit
- scroll with the mouse wheel or keyboard
- drag the scrollbar when content is long
- press `?` in the app for the full keyboard help

Common keys:

- `q` or `Ctrl-C`: quit
- `r`: refresh
- `n`: open another PR or issue in a resource tab
- `Ctrl-C` in the open-resource modal: clear input, then close when empty
- `Tab`, `Shift+Tab`, `Left`, `Right`: switch tabs
- `Up`, `Down`, `PageUp`, `PageDown`, `Home`, `End`: scroll
- `Enter`: activate the first visible link or action
- `y`: copy the first visible GitHub URL
- `o`: open the first visible GitHub URL
- `s`: settings
- `?`: help

## Configuration

The config file is:

```text
~/.config/ghzinga/config.toml
```

Default config:

```toml
[ui]
theme = "default"
symbols = "emoji"
spacing = "comfortable"
width_mode = "fixed"
fixed_width = 118
scrollbar = "on-scroll"
```

You can change theme, symbols, spacing, width, and scrollbar behavior from the
settings view inside the app.

## Sessions

`ghzinga` saves open PR/issue tabs and UI state under:

```text
~/.local/state/ghzinga
```

Cached GitHub resource snapshots are stored separately under:

```text
~/.cache/ghzinga
```

Environment overrides:

- `GZG_STATE_HOME`: alternate session state directory
- `GZG_CACHE_HOME`: alternate resource cache directory
- `GZG_RUNTIME_HOME`: alternate runtime socket directory for live session control
- `GZG_SESSION`: default named session

Session commands:

```sh
gzg sessions
gzg session show <id-or-name>
gzg session rename <id-or-name> <name>
gzg session delete <id-or-name>
```

Control a running session from another shell:

```sh
gzg open --session <id-or-name> dutifuldev/ghzinga#29
gzg set --session <id-or-name> theme solarized
gzg set --session <id-or-name> spacing comfortable
gzg set --session <id-or-name> width-mode fixed
gzg set --session <id-or-name> fixed-width 118
gzg set --session <id-or-name> scrollbar on-scroll
```

If the session is running, these commands update the live TUI without stealing
terminal focus. If it is not running, `gzg open` updates the saved session so the
resource appears on the next restore.

## Refresh

`ghzinga` refreshes automatically every 300 seconds by default. Use
`--refresh-seconds 0` to disable automatic refresh, or press `r` to refresh
manually.

When a resource has more data than the normal GitHub API depth loads, ghzinga
shows a full-depth action so you can fetch the rest without restarting the app.

## License

[MIT](LICENSE)
