{"id":45978309,"url":"https://github.com/maxbeizer/gh-agent-viz","last_synced_at":"2026-02-28T17:09:33.505Z","repository":{"id":339647517,"uuid":"1158110263","full_name":"maxbeizer/gh-agent-viz","owner":"maxbeizer","description":"a gh CLI extension to see what your agents are up to","archived":false,"fork":false,"pushed_at":"2026-02-20T18:46:08.000Z","size":761,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-20T23:54:00.258Z","etag":null,"topics":["agents","cli"],"latest_commit_sha":null,"homepage":"https://maxbeizer.github.io/gh-agent-viz/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maxbeizer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-14T20:14:55.000Z","updated_at":"2026-02-20T18:43:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maxbeizer/gh-agent-viz","commit_stats":null,"previous_names":["maxbeizer/gh-agent-viz"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/maxbeizer/gh-agent-viz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxbeizer%2Fgh-agent-viz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxbeizer%2Fgh-agent-viz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxbeizer%2Fgh-agent-viz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxbeizer%2Fgh-agent-viz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxbeizer","download_url":"https://codeload.github.com/maxbeizer/gh-agent-viz/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxbeizer%2Fgh-agent-viz/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29943874,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-28T13:49:17.081Z","status":"ssl_error","status_checked_at":"2026-02-28T13:48:50.396Z","response_time":90,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","cli"],"created_at":"2026-02-28T17:09:32.908Z","updated_at":"2026-02-28T17:09:33.494Z","avatar_url":"https://github.com/maxbeizer.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gh-agent-viz\n\nAn interactive terminal UI for visualizing GitHub Copilot coding agent sessions. Built as a `gh` CLI extension.\n\n![gh-agent-viz demo](docs/demo.gif)\n\n\u003e **Tip:** Run `gh agent-viz --demo` to explore the UI with sample data.\n\n## Features\n\n- 📊 **Interactive TUI** - Browse agent sessions with keyboard navigation\n- 📌 **Sessions at a Glance + Session Summary panel** - Fast status counts plus plain-language details/actions for the highlighted row\n- 🔍 **Task Details** - View comprehensive task metadata (status, repo, branch, PR links)\n- 📝 **Log Viewer** - Scrollable, searchable agent task logs\n- 💻 **Local Sessions** - Automatically ingests local Copilot CLI sessions from `~/.copilot/session-state/`\n- 🎨 **Status Indicators** - Color-coded status icons (running, queued, completed, failed)\n- ✋ **Input Needed Detection** - Highlights sessions that appear blocked waiting for human input\n- 🚦 **Action Reasons** - Every card includes an explicit `Needs your action:` reason (`waiting on your input`, `run failed`, `running but quiet`, or `no action needed`)\n- 🧭 **Action-First Ordering** - Sessions needing input/failure/quiet checks surface first, while older quiet duplicates are de-emphasized with a `↺ quiet duplicate` badge\n- ⚡ **Quick Actions** - Contextual hints only show actions available for the highlighted session\n- 🔄 **Resume Sessions** - Jump directly into active Copilot CLI sessions with one keystroke\n- ⌨️ **Vim-style Keys** - j/k navigation, familiar keybindings\n- 🛡️ **Tolerant Parsing** - Gracefully handles malformed session files without crashing\n- 🎯 **Kanban board view** — `K` to toggle status-column layout\n- 🔔 **Toast notifications** — status change alerts overlay\n- 📊 **Session timeline** — Unicode lifecycle bar in detail view\n- 🔗 **Dependency graph** — related session visualization\n- 🎨 **Color themes** — catppuccin-mocha, dracula, tokyo-night presets\n- 📡 **Live log tailing** — real-time log streaming with follow mode\n- 💬 **Conversation view** — styled chat bubbles for session dialogue\n- 🔧 **Tool timeline** — chronological trace of agent actions\n- 📊 **Mission control** — fleet summary dashboard\n- 🔍 **Diff view** — colored PR diffs in the TUI\n- ❓ **Help overlay** — `?` shows all keybindings\n\nSee [docs/UI_FEATURES.md](docs/UI_FEATURES.md) for a comprehensive guide to all visual features.\n\n## Installation\n\n### Install via GitHub CLI\n\n```bash\ngh extension install maxbeizer/gh-agent-viz\n```\n\n### Build from Source\n\nRequires Go 1.24.2 or newer.\n\n```bash\ngit clone https://github.com/maxbeizer/gh-agent-viz.git\ncd gh-agent-viz\ngo build -o bin/gh-agent-viz ./gh-agent-viz.go\n```\n\n### Install from Local Checkout (Development)\n\n```bash\ngh extension install .\n```\n\nThis local install path uses the repository's executable wrapper and runs with your installed Go toolchain.\n\nTo reload while developing, just run `gh agent-viz` again after code changes. Local installs cannot be upgraded with `gh extension upgrade`.\n\nIf you need to (re)link the local checkout, run:\n\n```bash\nmake relink-local\n```\n\n## Usage\n\nIf you want a fast walkthrough of what the board is showing, read [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md).\n\n### Launch the TUI\n\n```bash\ngh agent-viz\n```\n\n### Scope to a Specific Repository\n\n```bash\ngh agent-viz --repo owner/repo\n```\n\n### Enable Debug Mode\n\n```bash\ngh agent-viz --debug\n```\n\nDebug mode writes command diagnostics to `~/.gh-agent-viz-debug.log` to speed up troubleshooting.\nWhen enabled, the UI also shows a persistent debug banner with the log path.\n\n### Keyboard Shortcuts\n\n| Key | Action |\n|-----|--------|\n| `↑` / `↓` / `j` / `k` | Navigate sessions |\n| `enter` | View session details |\n| `esc` | Go back |\n| `l` | View logs |\n| `o` | Open PR in browser |\n| `s` | Resume session |\n| `x` | Dismiss session |\n| `r` | Refresh |\n| `p` | Toggle preview pane |\n| `K` | Toggle kanban view |\n| `tab` / `shift+tab` | Cycle filter tabs |\n| `a` | Jump to attention tab |\n| `g` | Cycle group-by mode |\n| `space` | Expand/collapse group |\n| `c` | Conversation view |\n| `t` | Tool timeline |\n| `d` | Diff view (list/detail); page down (in logs) |\n| `M` | Toggle mission control |\n| `?` | Toggle help overlay |\n| `!` | Open gh-agent-viz repo in browser |\n| `@` | File a new issue in browser |\n| `f` | Toggle follow mode (in logs) |\n| `u` | Page up (in logs) |\n| `g` / `G` | Top/bottom (in logs) |\n| `q` | Quit |\n\nAction hints in the footer are contextual: unavailable actions are hidden for the currently highlighted session.\n\n### Resume Active Sessions\n\nPress `s` on any active **local Copilot CLI session** (status: `running` or `queued`) to resume it directly in your terminal. This executes `gh copilot -- --resume \u003csession-id\u003e` and drops you into the Copilot CLI session.\n\n**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.\n\n### At-a-glance card semantics\n\nEach session card is intentionally labeled for quick triage:\n\n- `Repository:` shows linked repo context (`not available` when missing)\n- `Needs your action:` explains why it needs action now (or confirms `no action needed`)\n- Older repeated quiet sessions are intentionally de-emphasized (`↺ quiet duplicate`) to reduce list noise without hiding rows\n- `Last update:` shows recency using friendly wording like `not recorded` when metadata is missing\n- The **Session Summary** panel mirrors the same plain-language fields for the highlighted row\n\n### Log Viewer Navigation\n\nWhen viewing logs:\n\n| Key | Action |\n|-----|--------|\n| `j` / `↓` | Scroll down one line |\n| `k` / `↑` | Scroll up one line |\n| `d` | Scroll down half page |\n| `u` | Scroll up half page |\n| `g` | Go to top |\n| `G` | Go to bottom |\n| `f` | Toggle follow mode (live tailing) |\n| `esc` | Return to task list |\n\n## Configuration\n\nCreate a `.gh-agent-viz.yml` file in your home directory to customize settings:\n\n```yaml\n# List of repositories to watch\nrepos:\n  - owner/repo1\n  - owner/repo2\n\n# Refresh interval in seconds (default: 30)\nrefreshInterval: 30\n\n# Default status filter: all, attention, active, completed, failed (default: all)\ndefaultFilter: all\n\n# Color theme: default, catppuccin-mocha, dracula, tokyo-night, solarized-light\ntheme: catppuccin-mocha\n```\n\n## Documentation\n\n- **[Quick Docs Home](docs/index.md)** - Start here for product usage\n- **[Getting Started](docs/GETTING_STARTED.md)** - Understand what you are seeing on screen\n- **[Operator Guide](docs/OPERATOR_GUIDE.md)** - Daily workflows and keybindings\n- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Fast fixes for common issues\n- **[Debug Mode](docs/DEBUG_MODE.md)** - Capture actionable diagnostics\n- **[Developer Workflow](docs/DEVELOPER_WORKFLOW.md)** - Makefile commands for build/test/smoke\n- **[UI Features](docs/UI_FEATURES.md)** - Kanban, toasts, timeline, dependency graph, themes, live tailing, conversation view, tool timeline, diff view, mission control, help overlay\n- **[Architecture Decisions](docs/DECISIONS.md)** - Technical design rationale and patterns\n\n## Requirements\n\n- [GitHub CLI](https://cli.github.com/) (`gh`) installed and authenticated\n- GitHub Copilot CLI with agent-task commands available (used as fallback data source)\n\n## Architecture\n\nThis is a `gh` CLI extension (not a Copilot CLI plugin) because:\n\n- **Copilot CLI plugins** operate within the agent conversation model - they provide skills, MCP servers, and custom agents, but offer **no control over terminal UI**\n- **`gh` extensions** have full control over the terminal, enabling interactive TUI experiences\n\nSee [docs/DECISIONS.md](docs/DECISIONS.md) for detailed architecture decisions.\n\n## Security\n\nSecurity is a core requirement for this project. See [docs/SECURITY.md](docs/SECURITY.md) for security principles, threat surface, and required engineering practices.\n\n## Documentation Site\n\n- GitHub Pages is deployed from `docs/` via `.github/workflows/docs-pages.yml`.\n- Site URL: https://maxbeizer.github.io/gh-agent-viz/\n- If initial deploy cannot enable Pages automatically, enable GitHub Pages once in repository settings and rerun the Docs workflow.\n- Keep docs in sync with shipped behavior when merging changes.\n\n### Technology Stack\n\n- **Language**: Go\n- **TUI Framework**: [Bubble Tea](https://github.com/charmbracelet/bubbletea) + [Lip Gloss](https://github.com/charmbracelet/lipgloss) + [Bubbles](https://github.com/charmbracelet/bubbles)\n- **CLI Framework**: [Cobra](https://github.com/spf13/cobra)\n- **Data Source**: Copilot API (`api.githubcopilot.com`) with `gh agent-task` CLI fallback\n\n### Data Sources\n\ngh-agent-viz pulls sessions from two sources:\n\n1. **Remote Agent Tasks**: Primarily via direct HTTP to the Copilot API (`api.githubcopilot.com`), with `gh agent-task` CLI as fallback\n2. **Local Copilot Sessions**: From `~/.copilot/session-state/*/workspace.yaml`\n\nBoth sources are displayed together in the unified session list. See [docs/LOCAL_SESSIONS.md](docs/LOCAL_SESSIONS.md) for details on local session ingestion.\n\n### Project Structure\n\n```\ngh-agent-viz/\n├── gh-agent-viz.go          # Entry point\n├── cmd/                     # Cobra commands\n├── internal/\n│   ├── data/               # Data fetching (CAPI direct + CLI fallback)\n│   │   └── capi/           # Copilot API client\n│   ├── config/             # Configuration parsing\n│   └── tui/                # Bubble Tea UI components\n│       └── components/     # Header, footer, task list, detail, logs\n└── docs/                   # Architecture decisions\n```\n\n## Development\n\n### Prerequisites\n\n- Go 1.24.2 or later\n- GitHub CLI authenticated\n\n### One-command workflow (recommended)\n\n```bash\nmake build\nmake test\nmake smoke\n```\n\n### Full local validation (CI-like)\n\n```bash\nmake ci\n```\n\n### Additional developer commands\n\n```bash\nmake test-race\nmake coverage\nmake fmt\nmake lint\nmake clean\n```\n\nSee `make help` and [docs/DEVELOPER_WORKFLOW.md](docs/DEVELOPER_WORKFLOW.md).\n\n## Reference\n\nThis project follows patterns from [gh-dash](https://github.com/dlvhdr/gh-dash), the gold standard for interactive Bubble Tea `gh` extensions.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxbeizer%2Fgh-agent-viz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxbeizer%2Fgh-agent-viz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxbeizer%2Fgh-agent-viz/lists"}