cortex-tms dashboard
The cortex-tms dashboard command launches a full-screen interactive terminal UI showing real-time governance health for your TMS project — file tiers, staleness, sprint progress, validation status, and Guardian results in one place.
Synopsis
Section titled “Synopsis”cortex-tms dashboard [options]Description
Section titled “Description”The dashboard is built with React + Ink — it runs entirely in your terminal, no browser required. Navigate between three views using the 1, 2, 3 keys and quit with q or Ctrl+C.
Options
Section titled “Options”--live
Section titled “--live”Enable auto-refresh. The dashboard re-runs collectTMSStats() every 5 seconds and updates all cards.
cortex-tms dashboard --live--cwd <path>
Section titled “--cwd <path>”Run the dashboard against a different project directory instead of the current working directory.
cortex-tms dashboard --cwd /path/to/projectNavigate with number keys:
| Key | View | What you see |
|---|---|---|
1 | Overview | Governance score, staleness, sprint progress |
2 | Files | HOT files list, tier distribution, file size health |
3 | Health | Validation status, Guardian violations |
q | — | Quit the dashboard |
Overview View
Section titled “Overview View”Governance Health Score
Section titled “Governance Health Score”A composite 0–100 score calculated from validation status, Guardian results, and staleness data.
| Deduction | Reason |
|---|---|
| −40 pts | Validation errors |
| −20 pts | Validation warnings |
| −30 pts | Guardian major violations |
| −15 pts | Guardian minor issues |
Color coding: 🟢 green (80+) · 🟡 yellow (60–79) · 🔴 red (below 60)
Staleness Card
Section titled “Staleness Card”Shows git-based doc freshness when staleness detection is configured.
- Stale docs — count of docs flagged as outdated
- Total checked — how many governance docs were scanned
- Freshness % — percentage of docs still current
- Oldest doc — days since the least-recently-updated doc was touched
Only shown when staleness data is available (requires full git history).
Sprint Progress Card
Section titled “Sprint Progress Card”Reads your NEXT-TASKS.md sprint header and task markers:
- Sprint name and focus area
- Visual progress bar
- Done / In Progress / Todo task counts
Shows a “Not Configured” card if no sprint is detected in NEXT-TASKS.md.
Files View
Section titled “Files View”HOT Files Card
Section titled “HOT Files Card”Lists all files currently tagged as HOT tier — the files your AI agents will always read.
File Distribution Card
Section titled “File Distribution Card”Bar chart breakdown of HOT / WARM / COLD file counts across your project.
File Size Health Card
Section titled “File Size Health Card”Highlights any docs that are approaching or exceeding line limits (Rule 4). Only shown when oversized files are detected.
Health View
Section titled “Health View”Validation Card
Section titled “Validation Card”Mirrors the output of cortex-tms validate:
- Status — Healthy / Warnings / Errors / Unknown
- Violation count — number of issues found
- Last checked — relative timestamp of last validation run
Guardian Status Card
Section titled “Guardian Status Card”Shows the result of the last cortex-tms review run:
- Status — No violations / Minor issues / Major violations / Unknown
- Total violations — full count
- High-confidence violations — filtered to ≥70% confidence
- Last checked — relative timestamp
Examples
Section titled “Examples”# Open the dashboard and browse manuallycortex-tms dashboard# Auto-refresh every 5 secondscortex-tms dashboard --live# Dashboard for a project in another directorycortex-tms dashboard --cwd ~/projects/my-apiKeyboard Controls
Section titled “Keyboard Controls”| Key | Action |
|---|---|
1 | Switch to Overview view |
2 | Switch to Files view |
3 | Switch to Health view |
q | Quit |
Ctrl+C | Force quit |
How It Works
Section titled “How It Works”The dashboard calls the same collectTMSStats() pipeline used by cortex-tms validate and cortex-tms status. All data is read from:
.cortexrc— project configurationNEXT-TASKS.md— sprint detection- Git history — staleness detection (requires
fetch-depth: 0in CI) - Last validation/review results — validation and Guardian cards
No external API calls are made. All data is local.
Related Commands
Section titled “Related Commands”cortex-tms validate— run health checks (feeds the Health view)cortex-tms status— text-only health summary (no interactive UI)cortex-tms review— Guardian pattern review (feeds the Guardian card)