ADO Dashboard

ADO Dashboard is a keyboard-driven terminal dashboard for Azure DevOps (ADO). If you spend your day reviewing PRs, triaging work items, and managing AI coding sessions, this keeps all of it in your terminal, no browser tabs required.

Demo Mode

Try the dashboard instantly — no ADO credentials, no setup wizard, no real data.

ado-dashboard --demo
# or
ADO_DASHBOARD_DEMO=1 ado-dashboard

The --demo flag populates every tab with fictional Tolkien-themed fixture data (Middle-earth org, Fellowship project, Gandalf the Grey as user). It's perfect for screenshots, presentations, or just exploring the interface before connecting to a real ADO org. No Azure CLI calls are made.

Install & Run

Screenshots above and below were captured in --demo mode with fictional Middle-earth data.

git clone https://github.com/gaburn/ado-dashboard.git
cd ado-dashboard
pip install -e .
ado-dashboard

On first launch an interactive setup wizard walks you through configuration. Re-run it any time with ado-dashboard --setup.

Prerequisites

Requirement	Install / verify
Python 3.12+	python --version
Azure CLI (authenticated)	Install, then az login
azure-devops extension	az extension add --name azure-devops
Triage only: PowerShell (pwsh or powershell)	A Get-TriageItems.ps1.example template is included; copy and customise it, then set triage_script_path in Settings

Tabs

#	Tab	What it shows
1	My PRs	Active PRs you created (across multiple projects). Draft PRs are dimmed. Status column shows colored approval indicators: ✓ green (approved), ✗ red (rejected), ~ yellow (suggestions), · dim (no votes).
2	Reviewing	PRs where you are a reviewer. Vote status shown as ✓ approved / ✗ rejected / · pending. Declined PRs filtered out. Approved reviews highlighted green.
3	Work Items	ADO work items assigned to you. Filters out Closed, Done, Completed, Cut, and Resolved states.
4	Triage	On-call triage board with a board selector dropdown, priority groups, categorization, action plan, and clickable links. Switching boards refreshes the view with a loading indicator.
5	Copilot Sessions	Active Copilot CLI sessions with status, intent, and working directory. Press R (Shift+R) to resume an inactive session in a new Windows Terminal tab. Press f to focus the terminal of an active session.

Screenshots

Reviewing — PRs where you are a reviewer

Work Items — assigned items across Epic / Feature / Story / Task / Bug

Triage — priority-grouped board with AI-assisted categorization

Copilot Sessions — resumable AI sessions with intent and last-active timestamps

Keyboard Shortcuts

Key	Action
↑ ↓	Move between rows
Enter	Open detail view
Escape	Back to list / clear search
1–5	Switch tab
o	Open selected item in browser
c	Copy selected item to clipboard
r	Refresh data
/	Search / filter active tab
SHIFT+0–6	Sort by column
R (Shift+R)	Resume a Copilot session in new terminal tab
f	Focus terminal of active session
s	Settings screen
i	Investigate selected triage item (launches Copilot session)
I (Shift+I)	Investigate entire triage board
h	Help overlay
q	Quit

Configuration

Settings are resolved in order: CLI args → environment variables → config file → defaults.

Config file location: %LOCALAPPDATA%\ado-dashboard\config.json (Windows) or ~/.config/ado-dashboard/config.json (Linux/macOS).

Method	Example
Setup wizard	ado-dashboard (first run) or ado-dashboard --setup
CLI flag	--projects MyProject,OtherProject
In-app	Press s to open settings

CLI Flags

Flag	Description
--setup	Re-run the configuration wizard
--org	Azure DevOps organization URL
--projects	Comma-separated project list for PR queries
--user	User email for ADO queries

Environment Variables

Variable	Maps to
ADO_ORG_URL	Organization URL
ADO_PROJECT	Default project
ADO_USER_EMAIL	User email
TRIAGE_BOARD	Default triage board URL
INVESTIGATION_MODEL	Model for investigation sessions
INVESTIGATION_AGENT	Agent for investigation sessions
INVESTIGATIONS_DIR	Directory for investigation results
ADO_DASHBOARD_REPO_ROOT	Repository root (for skill discovery)

In Settings (s), the Triage Boards section lets you configure multiple boards with separate Name and URL fields, then add/remove entries dynamically. Boards are stored in config.json as [display_name, url] pairs.

UI Details

• Status bar — global counts per tab plus triage priority breakdown.
• Dark theme with ADO blue accent.
• Version displayed in the title bar, including git commit hash (e.g., v0.2.0 (a3b4c5d)) for detecting stale instances.
• AI triage — pluggable investigation backend (see docs/investigation.md) with rule-based fallback when no backend is configured.
• Triage board selector — dropdown to switch between configured ADO triage boards with a loading indicator while data refreshes.
• Investigation launcher — press i/I to launch AI-powered investigation sessions for triage items. Requires a configured InvestigationLauncher (see docs/investigation.md).
• Dynamic settings — investigation model and agent dropdowns are populated from the active launcher at runtime.
• Title cleanup — board name prefixes are automatically stripped from triage item titles for cleaner display.
• Search — press / to open a search bar that filters the active tab's table in real-time. Press Enter to keep the filter, Escape to clear it. Works on My PRs, Reviewing, Work Items, and Copilot Sessions tabs.

How It Works

ADO Dashboard is a Textual TUI. It calls the az CLI asynchronously to fetch data from Azure DevOps, keeping the UI responsive. Detail views fetch richer metadata in the background (az repos pr show, az boards work-item show). Triage data comes from a configurable PowerShell script (see docs/triage-and-investigation.md). Investigation sessions are launched via the configured InvestigationLauncher adapter (see docs/investigation.md).

---

Architecture

See docs/architecture.md for module map and async model.

---

For Contributors

Document	Contents
docs/architecture.md	Module map, dependency diagram, async model, screen lifecycle, state ownership
docs/ado-integration.md	az command shapes, auth assumptions, error handling, JSON mapping
docs/triage-and-investigation.md	PowerShell script contract, categorizer pipeline, AI enrichment, investigation launcher
docs/investigation.md	Pluggable InvestigationLauncher adapter: NoOpLauncher + custom backends
docs/configuration.md	Full 4-layer resolution, config schema, setup wizard, in-app settings
docs/development.md	Running locally, tests, adding a tab, adding a settings field, CSS conventions, known cruft

---

Troubleshooting / FAQ

az login not authenticated Run az login to sign in, then az account set --subscription <name-or-id> to select the right subscription.

No PRs or work items showing Verify your org URL in the config file (%LOCALAPPDATA%\ado-dashboard\config.json on Windows, ~/.config/ado-dashboard/config.json on Linux/macOS). Re-run ado-dashboard --setup to reconfigure from scratch.

PowerShell not found (Triage tab) Install pwsh or point the triage script to the Windows built-in powershell. PowerShell is only needed if you use the Triage tab.

Triage tab shows "No triage board configured" That's expected — Triage is opt-in. Press s to open Settings and add a board URL.

App shows version v0.2.1-dirty Your working tree has uncommitted changes. Commit or stash them and restart the app.