TUI Dashboard

A real-time terminal dashboard for monitoring autoresearch training runs on Apple Silicon, built with Textual.

Branch: feature/tui-dashboard

TUI Dashboard

Dashboard showing a training run in progress on Apple M5 Max — live metrics updating every ~1 second.

# From the repo root
git checkout feature/tui-dashboard
uv sync --extra tui # Textual only
# or
uv sync --extra all # All backends + TUI

# Launch dashboard with MLX training (default)
uv run dashboard.py
# Launch with MPS (PyTorch) training
uv run dashboard.py train.py
# Watch mode — show dashboard without starting training
uv run dashboard.py --watch
# Training scripts still work standalone (no TUI changes required)
uv run train_mlx.py

The dashboard runs the training script as a subprocess and parses its stdout in real-time. This means:

• Zero changes to training code — train_mlx.py and train.py are unmodified
• Process isolation — a training crash doesn't kill the dashboard
• Both backends supported — works with MLX and MPS identically

The training scripts output step metrics using print(..., end="", flush=True) with \r carriage returns for in-place line updates. The TUI uses a threaded byte-by-byte reader to capture each flush immediately, splitting on \r and \n to extract individual step updates.

dashboard.py Entry point
tui/
 __init__.py Package init
 app.py Textual Application — layout, subprocess management, keybindings
 widgets.py TrainingPanel, HardwarePanel, ExperimentsTable, ActivityLog
 parser.py Regex parser for training stdout (step metrics + final summary)
 hardware.py Apple Silicon hardware detection (wraps backends/__init__.py)
 experiments.py results.tsv loader for experiment history table
 styles.tcss Textual CSS for panel layout and styling

Output parsing: The parser uses regex to extract 9 per-step metrics from lines like:

step 00192 (62.3%) | loss: 4.168331 | lrm: 0.66 | dt: 1001ms | tok/sec: 32,737 | mfu: 23.0% | epoch: 1 | remaining: 118s

Final summary parsing: After training completes, the script outputs a --- separator followed by key-value pairs (val_bpb, peak_vram_mb, mfu_percent, etc.) which are parsed and displayed in the Training panel's completion view.

Hardware detection: Uses sysctl to identify the Apple Silicon chip, GPU core count, and total memory. Estimates peak bf16 TFLOPS based on per-generation FLOPS-per-core values (M1: 0.5T, M2: 0.55T, M3: 0.65T, M4: 0.7T, M5: 0.85T).

Apple Silicon limitations: GPU temperature and load percentage are not available on macOS without sudo powermetrics. The dashboard focuses on memory usage (the critical metric for unified memory pressure) and omits temp/load.

• Textual >= 3.0.0 (includes Rich as a transitive dependency)
• Pure Python, no binary dependencies
• Added as optional tui extra in pyproject.toml