An interactive terminal UI for visualizing GitHub Copilot coding agent sessions. Built as a gh CLI extension.

• 🎯 Dashboard-first — Multi-pane btop-style landing page with Active, Recent, Attention, Fleet, Repos, and Idle panels
• 📊 Stats bar — Always-visible summary of active, idle, done, and token usage
• 🔍 Fuzzy search — Press / to filter sessions by title, repo, branch, or status
• 🖱️ Mouse support — Scroll and click to focus panels
• 🎯 Kanban board — K to toggle status-column layout with compact cards
• 📸 Snapshot debugging — Press S to capture TUI state as JSON, or --snapshot <path> on launch
• 📌 Session detail — Comprehensive metadata, timeline, telemetry, and dependency graph
• 📝 Log viewer — Scrollable agent task logs with live tailing
• 💬 Conversation view — Styled chat bubbles for session dialogue
• 🔧 Tool timeline — Chronological trace of agent tool calls
• 🔍 Diff view — Colored PR diffs in the TUI
• 💻 Local sessions — Automatically ingests local Copilot CLI sessions from ~/.copilot/session-state/
• 🎨 Color themes — catppuccin-mocha, dracula, tokyo-night, solarized-light
• 🔔 Toast notifications — Status change alerts and action confirmations
• 🔄 Resume sessions — Jump directly into active Copilot CLI sessions with one keystroke
• ⌨️ Vim-style keys — j/k navigation, familiar keybindings
• ❓ Help overlay — ? shows all keybindings

See docs/UI_FEATURES.md for a comprehensive guide to all visual features.

gh extension install maxbeizer/gh-agent-viz

Requires Go 1.24.2 or newer.

git clone https://github.com/maxbeizer/gh-agent-viz.git
cd gh-agent-viz
go build -o bin/gh-agent-viz ./gh-agent-viz.go

gh extension install .

This local install path uses the repository's executable wrapper and runs with your installed Go toolchain.

To reload while developing, just run gh agent-viz again after code changes. Local installs cannot be upgraded with gh extension upgrade.

If you need to (re)link the local checkout, run:

make relink-local

If you want a fast walkthrough of what the board is showing, read docs/GETTING_STARTED.md.

gh agent-viz

gh agent-viz --repo owner/repo

gh agent-viz --debug

Debug mode writes command diagnostics to ~/.gh-agent-viz-debug.log to speed up troubleshooting. When enabled, the UI also shows a persistent debug banner with the log path.

Press s on any active local Copilot CLI session (status: running or queued) to resume it directly in your terminal. This executes gh copilot -- --resume <session-id> and drops you into the Copilot CLI session.

Note: Only active local sessions can be resumed. Attempting to resume a remote agent-task row, or a completed/failed session, shows a clear error message.

Create a .gh-agent-viz.yml file in your home directory to customize settings:

# List of repositories to watch
repos:
  - owner/repo1
  - owner/repo2

# Refresh interval in seconds (default: 30)
refreshInterval: 30

# Default view on launch: dashboard, table, kanban (default: dashboard)
defaultView: dashboard

# Color theme: default, catppuccin-mocha, dracula, tokyo-night, solarized-light
theme: catppuccin-mocha

• Quick Docs Home - Start here for product usage
• Getting Started - Understand what you are seeing on screen
• Operator Guide - Daily workflows and keybindings
• Troubleshooting - Fast fixes for common issues
• Debug Mode - Capture actionable diagnostics
• Developer Workflow - Makefile commands for build/test/smoke
• UI Features - Kanban, toasts, timeline, dependency graph, themes, live tailing, conversation view, tool timeline, diff view, mission control, help overlay
• Architecture Decisions - Technical design rationale and patterns

• GitHub CLI (gh) installed and authenticated
• GitHub Copilot CLI with agent-task commands available (used as fallback data source)

This is a gh CLI extension (not a Copilot CLI plugin) because:

• Copilot CLI plugins operate within the agent conversation model - they provide skills, MCP servers, and custom agents, but offer no control over terminal UI
• gh extensions have full control over the terminal, enabling interactive TUI experiences

See docs/DECISIONS.md for detailed architecture decisions.

Security is a core requirement for this project. See docs/SECURITY.md for security principles, threat surface, and required engineering practices.

• GitHub Pages is deployed from docs/ via .github/workflows/docs-pages.yml.
• Site URL: https://maxbeizer.github.io/gh-agent-viz/
• If initial deploy cannot enable Pages automatically, enable GitHub Pages once in repository settings and rerun the Docs workflow.
• Keep docs in sync with shipped behavior when merging changes.

• Language: Go
• TUI Framework: Bubble Tea + Lip Gloss + Bubbles
• CLI Framework: Cobra
• Data Source: Copilot API (api.githubcopilot.com) with gh agent-task CLI fallback

gh-agent-viz pulls sessions from two sources:

1. Remote Agent Tasks: Primarily via direct HTTP to the Copilot API (api.githubcopilot.com), with gh agent-task CLI as fallback
2. Local Copilot Sessions: From ~/.copilot/session-state/*/workspace.yaml

Both sources are displayed together in the unified session list. See docs/LOCAL_SESSIONS.md for details on local session ingestion.

gh-agent-viz/
├── gh-agent-viz.go          # Entry point
├── cmd/                     # Cobra commands
├── internal/
│   ├── data/               # Data fetching (CAPI direct + CLI fallback)
│   │   ├── capi/           # Copilot API client
│   │   └── snapshot.go     # Machine-readable TUI state capture
│   ├── config/             # Configuration parsing
│   └── tui/                # Bubble Tea UI components
│       └── components/     # Dashboard, kanban, stats bar, header, footer, etc.
└── docs/                   # Documentation and architecture decisions

• Go 1.24.2 or later
• GitHub CLI authenticated

make build
make test
make smoke

make ci

make test-race
make coverage
make fmt
make lint
make clean

See make help and docs/DEVELOPER_WORKFLOW.md.

This project follows patterns from gh-dash, the gold standard for interactive Bubble Tea gh extensions.

MIT