Dashboard Reference

Overview

The Longshot Dashboard is a fullscreen Rich terminal UI that provides real-time monitoring of the orchestrator’s massively parallel coding operations. It reads NDJSON events and renders a multi-panel dashboard at 4 Hz.

Installation

pip install rich

Usage Modes

Piped from Orchestrator (Production)

node packages/orchestrator/dist/main.js | python dashboard.py --stdin

Or via CLI integration:

longshot "Build an app" --dashboard

Follow Latest Logs (Development)

python dashboard.py --follow

Tails the latest logs/run-*.ndjson file live, similar to tail -f. Automatically switches to newer log files when they appear.

Demo Mode (No Orchestrator)

python dashboard.py --demo
python dashboard.py --demo --agents 100

Generates synthetic event data for testing and demonstration.

Replay Mode

python dashboard.py --replay logs/run-20260303-154233.ndjson
python dashboard.py --replay logs/run-latest.ndjson --speed 2.0

Replays a recorded NDJSON log file, preserving original timestamp deltas.

Command-Line Arguments

Input Sources

--stdin

Read NDJSON from stdin (orchestrator pipe)

--follow

Tail latest logs/run-*.ndjson file live

--replay FILE

Replay NDJSON log file

--demo

Generate synthetic demo data

Configuration

--agents N

Maximum agent slots (default: 24)
Used in demo mode

--features N

Total features to build in demo (default: 80)

--speed FACTOR

Replay speed multiplier (default: 1.0)
2.0 = 2x faster, 0.5 = half speed

--cost-rate RATE

Cost per 1K tokens in dollars (default: 0.001)

Layout Structure

The dashboard uses a multi-panel layout:

┌─────────────────────────────────────────────────────────┐
│  HEADER (elapsed, active workers, merged count)         │
├──────────────┬──────────────────────────────────────────┤
│   METRICS    │                                          │
│              │          PLANNER TREE                    │
│   (stats)    │      (In Progress | Completed)           │
│              │                                          │
├──────────────┤          OR                              │
│              │                                          │
│ MERGE QUEUE  │         ACTIVITY FEED                    │
│              │                                          │
│  (success)   │                                          │
└──────────────┴──────────────────────────────────────────┘
│             FOOTER (task progress bar)                  │
├─────────────────────────────────────────────────────────┤
│             CONTROLS (zoom, scroll, tab)                │
└─────────────────────────────────────────────────────────┘

Panels

Header (3 lines)

Elapsed time
Active workers count
Total merged branches
Planner thinking indicator

Left Column - Metrics

Iteration number
Commits per hour
Completed/Failed/Pending tasks
Merge success rate
Token usage (with in-flight estimate)
Estimated cost
Recent velocity sparkline
Running workers

Left Column - Merge Queue

Success rate bar
Merged count
Conflicts count
Failed merges count

Right Column - Planner Tree (Default Tab)

In Progress pane: Active and pending tasks
Completed pane: Finished and failed tasks
Hierarchical tree view with:
- Progress meters (■■■■)
- Task IDs and descriptions
- Status (running, complete, failed, etc.)
- Duration timers
- Worker progress details
- Handoff metrics (lines added/removed, files, tokens)

Right Column - Activity Feed (Alt Tab)

Real-time event log (50 most recent)
Color-coded by event type
Timestamps

Footer (3 lines)

Overall task completion progress bar

Controls (3 lines)

Current tree zoom level
Available keyboard shortcuts
Active tab indicator

Keyboard Controls

Tab

Switch between Agent Grid and Activity tabs

+ / -

Zoom planner tree levels in/out
Shows more or fewer levels of task hierarchy

Scrolling

In Progress Pane:

w - Scroll up
s - Scroll down

Completed Pane:

e - Scroll up
d - Scroll down

Planner Tree

Node Types

root - Root planner (top level)
plan - Primary planner agents
sub - Subplanner decompositions
wkr - Individual worker tasks

Status Colors

running - Bright yellow
complete - Bright green
failed - Bright red
assigned - Cyan
pending - Blue
cancelled - Bright red

Progress Meters

■■■■  100% complete (green)
■■■□   75% complete (green + gray)
■□□□   25% complete (green + gray)
□□□□    0% complete (gray)
■■■■  Failed (red)

Node Information Display

Each node shows:

■■■□ agent-001-sub-2 (wkr) "Implement auth" running [2m34s] > Writing tests... +145/-23 3f 8.2Ktok

Progress meter
Task ID (truncated if > 20 chars)
Role label (root/plan/sub/wkr)
Description (truncated at 32 chars)
Status
Duration timer (if running, color-coded by age)
Worker progress message (if available)
Handoff metrics (if complete):
- Lines added/removed
- Files changed
- Tokens used

Hierarchical Display

Tasks are organized in a tree structure:

├─ agent-001 (plan)
│  ├─ agent-001-sub-1 (wkr) complete
│  ├─ agent-001-sub-2 (sub) running
│  │  ├─ agent-001-sub-2-sub-1 (wkr) complete
│  │  └─ agent-001-sub-2-sub-2 (wkr) running
│  └─ ... 5 hidden
└─ agent-002 (plan)

Zoom Levels

The +/- keys control visible depth:

Level 1 - Shows only top-level planners
Level 2 - Shows planners + their immediate children
Level 3+ - Shows deeper subplanner hierarchies

Hidden nodes are indicated with ... N hidden

Metrics Display

Velocity Sparkline

Shows task completion rate over the last 5 minutes:

Velocity  ▁▂▃▄▅▆▇█▇▆  12.3/min

10 buckets of 30 seconds each
Height represents completions in that bucket
Current rate displayed numerically

Token Usage

Tokens  1.2M (~+450K wip)

Total tokens used (formatted as K/M)
Estimated in-flight tokens from active workers

Merge Success Rate

Merge rate  94.2%

Color-coded:

Green - > 90%
Yellow - 70-90%
Red - < 70%

Activity Feed Events

Event Types and Colors

Task Created (Cyan)

15:42:33   + agent-001  Implement user authentication

Task Completed (Green/Red)

15:45:12   agent-001  complete
15:45:15   agent-002  failed

Merge Result (Green/Yellow/Red)

45:20   >> merged  worker/agent-001
45:25   !! conflict  worker/agent-002
45:30   xx merge fail  worker/agent-003

Iteration Complete (Blue)

15:46:00   -- iteration 5  (12 tasks)

Worker Progress (Cyan/Dim)

15:43:05   ⚙ agent-001  Running tests...
15:43:10   ▸ agent-001  Cloning repo...

Reconciler (Yellow)

15:50:00   reconciler  3 fix tasks

Sweep Check (Green/Red)

15:51:00   sweep: all green
15:51:05   sweep: NEEDS FIX

Timeout/Error (Bold Red)

16:00:00   TIMEOUT  agent-042
16:00:05   ERR  Worker crashed: connection refused

State Management

DashboardState

Thread-safe state container with:

active_workers - Currently running tasks
pending_tasks - Tasks waiting for workers
completed_tasks - Finished tasks
failed_tasks - Failed tasks
commits_per_hour - Throughput metric
merge_success_rate - Merge queue health
total_tokens - Cumulative token usage
estimated_in_flight - Tokens from active workers
tree - PlannerTreeState (hierarchical task structure)
activity - Recent event feed (max 50)
visible_levels - Current zoom level
active_tab - Current tab (“grid” or “activity”)

PlannerTreeState

Recursive tree structure tracking:

parent - Parent node mapping
children - Child nodes list
status - Node status (pending, running, complete, etc.)
role - Node role (root-planner, planner, subplanner, worker)
desc - Task description
started_at - Start timestamp
worker_progress - Real-time progress messages
handoff_metrics - Completion metrics

Event Ingestion

The dashboard processes NDJSON events:

Key Events

“Metrics” - Periodic snapshot from Monitor

{
  "message": "Metrics",
  "data": {
    "activeWorkers": 12,
    "pendingTasks": 8,
    "completedTasks": 45,
    "totalTokensUsed": 1234567,
    "commitsPerHour": 180.5
  }
}

“Task status” - State transition

{
  "message": "Task status",
  "data": {
    "taskId": "agent-001",
    "from": "pending",
    "to": "running"
  }
}

“Task created” - New task

{
  "message": "Task created",
  "data": {
    "taskId": "agent-001",
    "desc": "Implement authentication",
    "parentId": "root-planner"
  }
}

“Task completed” - Finish with metrics

{
  "message": "Task completed",
  "data": {
    "taskId": "agent-001",
    "status": "complete",
    "linesAdded": 342,
    "linesRemoved": 18,
    "filesChanged": 5,
    "tokensUsed": 12450,
    "durationMs": 45000
  }
}

“Worker progress” - Real-time updates

{
  "message": "Worker progress",
  "data": {
    "taskId": "agent-001",
    "phase": "sandbox",
    "detail": "Running tests..."
  }
}

Refresh Rate

The dashboard refreshes at 4 Hz (250ms interval) for smooth real-time updates.

Terminal Requirements

Minimum size: 40 columns × 28 lines
Recommended: 120 columns × 40 lines
Terminal features: ANSI color support, UTF-8 encoding

Performance

The dashboard efficiently handles:

Activity buffer: 50 events (deque with maxlen)
Completion times: 300 events (5 minutes for velocity)
Tree nodes: Unlimited (dynamic rendering with scroll)

Packages

Core

Orchestrator

Sandbox

CLI

​Overview

​Installation

​Usage Modes

​Piped from Orchestrator (Production)

​Follow Latest Logs (Development)

​Demo Mode (No Orchestrator)

​Replay Mode

​Command-Line Arguments

​Input Sources

​Configuration

​Layout Structure

​Panels

​Keyboard Controls

​Navigation

​Scrolling

​Planner Tree

​Node Types

​Status Colors

​Progress Meters

​Node Information Display

​Hierarchical Display

​Zoom Levels

​Metrics Display

​Velocity Sparkline

​Token Usage

​Merge Success Rate

​Activity Feed Events

​Event Types and Colors

​State Management

​DashboardState

​PlannerTreeState

​Event Ingestion

​Key Events

​Refresh Rate

​Terminal Requirements

​Performance

Build docs developers (and LLMs) love