Skip to content

Issue PR Triage

Jump to bottom
Griffen Fargo edited this page May 15, 2026 · 2 revisions

Issue & PR Triage

Coco's GitHub triage workflow (#882) brings issue and pull-request review into the same terminal-native muscle memory as the rest of the workstation. Two complementary surfaces:

  • CLI: coco issues and coco prs print formatted, filterable lists to stdout — composable with grep, jq, and other pipeline tools.
  • TUI: gi (issues) and gP (PR triage) inside coco ui open list-on-left / inspector-on-right surfaces with full action keys.

Both surfaces share the underlying gh CLI for data access, so anything that works from the shell works inside the workstation. Authentication is whatever your gh auth status reports — no separate token setup.

Requirements

  • gh CLI installed and authenticated (gh auth login)
  • The current repository has a GitHub remote (origin or fallback)

Coco surfaces a friendly empty state when either requirement is missing, so the failure mode is discoverable rather than a stack trace.

CLI

coco issues

List issues in the current repository.

# Open issues (default)
coco issues

# Filter by state, assignee, author, labels
coco issues --state closed
coco issues --assignee @me        # shorthand: coco issues --mine
coco issues --author gfargo
coco issues --label bug,critical
coco issues --search "auth flow"

# Tune the page size
coco issues --limit 50

# JSON output for pipelines
coco issues --json | jq '.[] | .title'

# Disable / force-refresh the on-disk cache
coco issues --no-cache
coco issues --refresh

Every option maps 1:1 to the corresponding gh issue list flag, so anything gh accepts here works the same way.

coco prs

Same shape, for pull requests.

# Open PRs (default)
coco prs

# State (PRs have a merged variant distinct from closed)
coco prs --state merged
coco prs --state all --limit 5

# Targeting
coco prs --draft
coco prs --mine                   # = --author @me
coco prs --base main
coco prs --head feature/auth

# Free-form search syntax
coco prs --search "is:open is:public-good"

Disk cache

Both commands cache responses on disk under ~/.cache/coco/github/ (or $XDG_CACHE_HOME/coco/github/) with a 5-minute TTL. Triage is bursty — you tend to run coco issues a dozen times in a few minutes, then not touch it for hours — so the cache pays for itself quickly.

# Force a fresh gh call (writes through to cache)
coco issues --refresh

# Skip the cache entirely (no read, no write)
coco issues --no-cache

# Clear the entire triage cache directory
coco cache clear-github

The repo header tag on cache hits reads cached Ns ago so you can always tell when a list is fresh vs warm.

TUI

Inside coco ui:

Chord Surface
g i Issues triage list
g P Pull-request triage list (capital P; lowercase g p keeps targeting the existing single-PR action panel for the current branch)

The two triage surfaces are independent of the single-PR view — g p continues to show the rich action panel for the current branch's PR with status checks, reviews, and merge buttons. Use g P when you want to triage across many PRs.

Layout

Each surface follows the standard workstation chrome:

  • List (main panel): rows of #number state glyphs author branch title [labels] with color-coded state, draft/mergeable glyphs, and review-decision markers. Cursor with j / k or arrows; PageUp / PageDown page through.
  • Inspector (right pane): metadata for the cursored row — state, author, branches, labels, assignees, mergeable status, review decision, timestamps, URL.
  • Inspector hydration: when the cursor rests on a row for ~250ms, Coco fetches the item's body, comments, and (for PRs) reviews and status checks. Rapid j/k navigation never fires a gh call — only intentional rests. The hydrated detail caches per session, so cursoring back to a previously-viewed item shows instantly.

The header shows a ▼ <preset> indicator next to the row count — press f to cycle.

Action keys

Both views support the same scanning + acting flow. Destructive actions (close, reopen, merge, approve, request-changes) route through Coco's standard y-confirm prompt.

Common (both views)

Key Action
j / k / arrows Move the cursor
PageUp / PageDown Page through the list
/ Filter the visible list by free text (title, author, labels, assignees)
f Cycle through canned filter presets (see below)
O Open the cursored item's URL in the browser
y Yank the cursored item's URL to the clipboard
c Add a comment (multi-line prompt; Ctrl+D to submit)
L Add a label (single-line prompt)
A Add an assignee (single-line prompt; defaults to @me)
< / Esc Pop the view, returning to the previous surface

Issues view only

Key Action
x Close the cursored issue (y-confirm)
X Reopen the cursored issue (y-confirm — useful to undo a stray close)

PR triage view only

Key Action
m Merge — prompts for strategy (merge / squash / rebase), then y-confirm
x Close without merging (y-confirm)
a Approve (y-confirm)
R Request changes — multi-line review body prompt (Ctrl+D to submit), then y-confirm

These match the chord set on the single-PR action panel (g p) exactly, so muscle memory carries over. The triage view targets the cursored PR by number rather than the current branch.

Filter presets

f cycles through canned filters that compile to the same --state / --assignee / --author / etc. knobs the CLI accepts. The active preset shows in the surface header (▼ open, ▼ mine, ...).

Issues: open → closed → mine (open + assigned to me) → assigned → wrap

Pull requests: open → draft → mine (open + authored by me) → assigned → closed → merged → wrap

The presets aren't 1:1 across the two surfaces by design:

  • Issues have no draft / mergeable concept, so those presets are skipped on the issue list.
  • PRs have a merged state distinct from closed; issues don't.
  • mine semantics differ: for issues it means I'm the assignee (issues are tasks people pick up); for PRs it means I authored it (PRs are work people post).

Inspector content

Pre-hydration, the inspector renders the metadata available from the list payload — title, state, author, branches, labels, mergeable / review markers, timestamps, URL.

Post-hydration (250ms cursor rest), the inspector gains:

Issues

  • Body excerpt (first 6 non-empty lines, with a … N more lines trailer)
  • Comments section — total count + 3 most recent in @author: body form

Pull requests

  • Body excerpt
  • Status checks summary — pass / fail / pending counts
  • Reviews section — per-reviewer state (approved / changes requested / commented) with inline body excerpt
  • Comments section

Empty sections are omitted — a low-activity issue or PR doesn't pad the right pane with empty headings.

Cache behavior across mutations

When you mutate a row through one of the action keys (c, L, A, x, m, etc.), Coco:

  1. Drops the in-memory list cache for the active surface so the next render refetches with fresh state.
  2. Drops the mutated item's detail entry from the per-session detail cache so the inspector hydrates fresh on the next cursor rest.
  3. Wipes the on-disk cache (~/.cache/coco/github/) so any subsequent coco issues / coco prs CLI call sees the change immediately.

This is intentionally aggressive — the cost of a refetch is much smaller than the cost of showing stale data right after an action.

Tips

  • Pair the views. Cycle gi ↔ gP to triage issues that gate PRs and PRs that close issues. The breadcrumb in the header shows the path.
  • / and f compose. Set a preset with f, then / to narrow within it. Filter survives across navigation.
  • Use --json for one-offs. A quick coco issues --label bug --json | jq '.[] | "\(.number) \(.title)"' is faster than launching the workstation for read-only spelunking.
  • Open in browser, then come back. O opens the cursored URL; the workstation keeps running. Close the browser tab and your cursor is exactly where you left it.

Related

Clone this wiki locally