Runs Dashboard UI
Relevant source files
The following files were used as context for generating this wiki page:
The Runs Dashboard UI provides the interface for managing and monitoring AI-driven software development tasks. It displays the progress of agentic "runs," where AI agents attempt to resolve GitHub issues by planning changes, implementing code, and opening pull requests.
The UI consists of a central dashboard for high-level oversight, a detailed run view for monitoring specific event timelines, and a sidebar for rapid navigation between active tasks. It integrates human-in-the-loop controls, requiring manual approval for proposed plans before the implementation stage begins.
Sources: apps/web/src/pages/runs.tsx, apps/web/src/pages/run.tsx, README.md:16-19
Navigation and Run Organization
The system organizes runs into three primary categories based on their current state and the required human action. The groupRuns utility sorts these for display in both the home page and the sidebar.
| Category | Description |
|---|---|
| Needs you | Runs in states like awaiting_approval where a human must review a plan or pull request. |
| Working | Active runs where the agent is currently planning, implementing, or checking code. |
| Done | Runs that have reached a terminal state (merged, closed, failed, or cancelled). |
Sources: apps/web/src/pages/runs.tsx:88-99, apps/web/src/sidebar.tsx:102-120
Sidebar Component
The Sidebar component provides global navigation. It allows users to filter runs by repository and provides keyboard shortcuts (Alt+Up/Down) to cycle through the list. It displays a StatusDot for each run, colored by the specific run and pull request state.
Sources: apps/web/src/sidebar.tsx:32-58, apps/web/src/sidebar.tsx:71-85
Detailed Run View
The Detail View (RunPage) displays the lifecycle of a single issue resolution. It tracks the real-time activity of the agent through an EventSource stream.
Run Lifecycle States
The UI tracks progress through defined steps: Plan, Review, Implement, Check, and Result. The visual status of these steps is determined by the run's current state and terminal status.
The diagram shows the transition of a run from initial queuing through implementation and final PR status.
Sources: apps/web/src/pages/run.tsx:94-114, apps/web/src/status.ts:38-44
Event Timeline
The Conversation component renders the history of a run. It groups consecutive agent tool calls into "WorkGroups" to reduce visual clutter. Users can expand these groups to see specific file reads, shell commands, or network calls.
- Tool Folding: Consecutive
agent.toolevents are collapsed into a summary row. - Refused Hosts: Network attempts blocked by the egress proxy are highlighted as warnings.
- Stage Headers: Sections like "Plan" and "Implement" display a
StageClockthat ticks in real-time if the stage is active.
Sources: apps/web/src/run/conversation.tsx:80-112, apps/web/src/run/conversation.tsx:408-450
Human-in-the-Loop Interaction
A critical feature of the dashboard is the ReviewBar. This sticky component appears when a run enters the awaiting_approval state.
- Plan Review: The agent presents a Markdown plan in a
PlanCard. - Approve: Clicking "Approve plan" triggers a POST request to
/api/runs/{runId}/approve. - Request Changes: Users can provide feedback via a
Textarea. This sends a POST request to/api/runs/{runId}/request-changeswith the feedback body, returning the agent to the planning stage.
Sources: apps/web/src/pages/run.tsx:216-258, apps/web/src/run/conversation.tsx:132-156
Data Flow and State Management
The dashboard uses a combination of REST APIs and Server-Sent Events (SSE) to maintain UI synchronization with the backend.
The diagram illustrates the initial fetch of runs and the persistent connection for individual run updates.
Sources: apps/web/src/pages/run.tsx:23-38, apps/web/src/sidebar.tsx:16-22
Automated Scrolling
The Detailed View implements a useFollow hook. If a user is near the bottom of the page, the UI automatically scrolls to show new incoming events. If the user scrolls up to inspect previous work, auto-scroll pauses and a "New activity" button appears to return to the bottom.
Sources: apps/web/src/pages/run.tsx:43-70
Summary of Technical Components
| Component | Responsibility |
|---|---|
RunCard / RunRow | Displays individual run metadata, status dots, and relative timestamps. |
Steps | Renders a horizontal progress bar of the run lifecycle. |
WorkGroup | Collapses repetitive agent actions (e.g., Grep, Read, Bash) into a single interactive row. |
ChecksCard | Summarizes the result of automated code quality checks, including file changes and findings. |
RefusedNote | Alerts the operator to blocked egress traffic attempts by the agent. |
Sources: apps/web/src/pages/runs.tsx:30-49, apps/web/src/run/conversation.tsx:327-356, apps/web/src/run/conversation.tsx:378-406