gh-agent-viz

Getting Started

If the interface feels confusing at first, start here.

1) Launch with focus

gh agent-viz --repo owner/repo

Starting with one repo makes the session list much easier to read.

2) What you are looking at

The main screen shows a session list with a preview pane for the highlighted row. Each row displays status, title, repository, and timing information for quick scanning.

Each row is labeled for fast scanning:

status icon + title (+ badge) Repository: ... Needs your action: ... • Last update: ...

Attention reasons are explicit:

• waiting on your input
• run failed
• running but quiet (running/queued but stale)
• no action needed

Example:

🟢 Add retry logic Repository: maxbeizer/gh-agent-viz Needs your action: no action needed • Last update: 5m ago

3) Why you may see “Untitled Session” or “not available / not recorded”

This usually means older/local session metadata is incomplete.

• Untitled Session = session didn’t store a usable summary/title
• not available = repository/branch metadata was unavailable
• not recorded = no reliable timestamp signal was found

To reduce noise:

1. Use --repo owner/repo
2. Press a to jump straight to sessions that need your attention
3. Press r to refresh

4) Core controls (minimum set)

• j / k: move selection
• enter: open details
• l: open logs (remote rows)
• o: open PR (remote agent rows)
• s: resume active local session
• tab / shift+tab: change filter forward/backward
• a: toggle needs-action view
• p: toggle preview pane
• ?: show all keyboard shortcuts
• q: quit

5) First useful workflow

1. Filter to needs-action view (a)
2. Open a row (enter)
3. Check logs (l) if needed
4. Open PR (o) or resume (s) depending on row source

6) Views & Visualizations

gh-agent-viz includes several visual features beyond the default list view:

• Kanban board (K) — status-column layout for monitoring many sessions at once
• Toast notifications — automatic alerts when session statuses change
• Session timeline bar — Unicode lifecycle visualization in detail view
• Dependency graph — related session visualization in detail view
• Color themes — configurable presets (catppuccin-mocha, dracula, tokyo-night)
• Live log tailing — real-time log streaming with follow mode (f in log viewer)

See UI_FEATURES.md for the full guide.

This site is open source. Improve this page.