SP//dr Terminal Dashboard

███████╗██████╗     ██╗    ██╗██████╗ ██████╗
██╔════╝██╔══██╗   ██╔╝    ██╔╝██╔══██╗██╔══██╗
███████╗██████╔╝  ██╔╝    ██╔╝ ██║  ██║██████╔╝
╚════██║██╔═══╝  ██╔╝    ██╔╝  ██║  ██║██╔══██╗
███████║██║     ██╔╝    ██╔╝   ██████╔╝██║  ██║
╚══════╝╚═╝     ╚═╝     ╚═╝    ╚═════╝ ╚═╝  ╚═╝
       MECH COCKPIT TERMINAL DASHBOARD v1.0

A fully immersive mech-pilot HUD for your terminal. Every system metric is reframed through the lens of piloting the SP//dr mech suit — because staring at boring system monitors is for civilians.

---

Screenshot

╔════════════════════════════════════════════════════════════════════╗
║  SP//DR COCKPIT                         MECH CONTROL INTERFACE    ║
╠══════════════════╦═══════════════════════════╦════════════════════╣
║ ◈ THRUSTER ARRAY ║ ◈ UPLINK STATUS           ║  ◈ MISSION CLOCK  ║
║ TOTAL: 23.4%     ║ ▲ UPLINK   0.44 KB/s      ║  ██ ██ ██ ██ ██  ║
║ T01 ████░░░░ 42% ║ ▁▂▁▁▁▁▂▃▁▁▁▂▁▁▁▁▁▁▁▁▁▁▁▁ ║  12:34:56        ║
║ T02 ██░░░░░░ 18% ║ ▼ DOWNLINK 1.02 MB/s      ║                  ║
║ T03 ██░░░░░░ 21% ║ ▃▄▅▃▂▁▂▃▄▅▆▄▃▂▁▂▃▄▃▂▁▁▁▁ ║  SP//DR ONLINE   ║
║ T04 ███░░░░░ 33% ║ OPEN CHANNELS:   14        ║  002H 17M 44S    ║
╠══════════════════╠═══════════════════════════╣  MISSION DATE:   ║
║ ◈ NEURAL SYNC    ║ ◈ ACTIVE SUBROUTINES       ║  2026-05-25      ║
║  47.3% ███░░░░░░ ║ PID   NAME       CPU%  MEM%║                  ║
║ ALLOC : 7.54 GiB ║ 1234  firefox    12.4   3.2║                  ║
║ TOTAL :15.93 GiB ║ 5678  python      8.1   1.1║                  ║
╠══════════════════╩═══════════════════════════╩════════════════════╣
║  ●  ALL SYSTEMS NOMINAL  |  SP//DR ONLINE  |  THREAT LEVEL: ZERO ║
╚════════════════════════════════════════════════════════════════════╝

---

Requirements

• Python 3.10+
• A terminal emulator with 256-colour support (iTerm2, Windows Terminal, kitty, Alacritty, GNOME Terminal, etc.)
• Minimum terminal size: 120 × 36 characters recommended

---

Installation

Quick start (no install)

git clone https://github.com/yourname/spdr-dashboard
cd spdr-dashboard
pip install textual psutil tomli        # tomli only needed on Python < 3.11
python main.py

Install as a command with pipx

pipx install .
spdr

Install with pip in a virtual environment

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e .
python main.py

---

Configuration

Edit config.toml in the project root:

[dashboard]
refresh_rate_ms = 500           # how often metrics refresh (milliseconds)
color_theme     = "spdr_blue"   # spdr_blue | combat_red | stealth_black

[thresholds]
cpu_warn = 70   # CPU % that triggers a WARNING alert
cpu_crit = 90   # CPU % that triggers a CRITICAL alert
ram_warn = 75   # RAM % that triggers a WARNING alert
ram_crit = 85   # RAM % that triggers a CRITICAL alert

---

Keyboard Hotkeys

Key	Action
q	Quit / Eject pilot
t	Cycle colour theme
r	Reset / silence alerts (10 s)
1	Focus CPU thruster panel
2	Focus RAM neural-sync panel
3	Focus network uplink panel
4	Focus active subroutines panel
k	Kill selected process (in proc panel)
s	Suspend selected process

---

Panels

Panel	Mech Label	Data Source
CPU Usage	THRUSTER ARRAY	psutil.cpu_percent()
RAM Usage	NEURAL SYNC CAPACITY	psutil.virtual_memory()
Network I/O	UPLINK STATUS	psutil.net_io_counters()
Process Table	ACTIVE SUBROUTINES	psutil.process_iter()
Clock / Uptime	MISSION CLOCK	datetime, psutil.boot_time()
Alert Strip	THREAT DETECTION	Threshold evaluation

---

Colour Themes

Theme Name	Vibe
spdr_blue	Default teal-blue mech cockpit
combat_red	High-alert war mode, crimson UI
stealth_black	Dark ops, minimal light signature

Press t at runtime to cycle through them.

---

Project Structure

spdr-dashboard/
├── main.py               # Entry point — reads config, boots app
├── config.toml           # User configuration
├── pyproject.toml        # Packaging metadata
├── README.md
└── src/
    ├── app.py            # Textual App class, layout, bindings
    ├── alerts.py         # Threshold detection and alert structs
    ├── panels/
    │   ├── cpu.py        # Thruster Array widget
    │   ├── ram.py        # Neural Sync Capacity widget
    │   ├── network.py    # Uplink Status widget
    │   ├── processes.py  # Active Subroutines DataTable widget
    │   └── clock.py      # Mission Clock widget
    └── themes/
        ├── spdr_blue.tcss
        ├── combat_red.tcss
        └── stealth_black.tcss

---

Troubleshooting

"No module named textual" — run pip install textual psutil

Network channels show "REQUIRES ROOT ACCESS" — psutil.net_connections() needs elevated privileges on some systems. Run with sudo python main.py or the count will show as unavailable (speeds still work fine).

Terminal too small — resize to at least 120 columns × 36 rows. The layout will adapt but needs reasonable space.

macOS: process kill fails — System Integrity Protection may block killing certain processes. This is expected.

---

License

MIT — hack it, mod it, make it yours. Suit up.