vigil tui

Here's a concise, professional technical briefing for the vigil-tui repository, written in the style of a senior AI engineer consultant report.

Technical Briefing: vigil-tui Real-time terminal power monitor — CPU · GPU · RAM wattage dashboard Consultant-grade assessment | 26 Python files | 132 functions | 0 test files

Overview

vigil-tui is a terminal-based dashboard written in Python that visualizes live wattage, thermals, clock speeds, efficiency scores, and electricity cost for CPU, GPU, and RAM. It queries hardware sensors directly (hwmon, RAPL, LibreHardwareMonitor, NVML) and renders a Braille-charted dashboard with per-component efficiency and cost tracking. The codebase is structured as a single-package TUI application with a pyproject.toml/requirements.txt pip-based setup.

Clone: git clone https://github.com/moses-y/vigil-tui

Code Health & Issues

All findings below are deterministic, produced by static analysis of the repository's source. They are not opinions.

Severity	Count	Issue	Files
HIGH	3	No test suite — 26 source files with zero test coverage	Repository-wide
HIGH	1	Dependencies declared without a lockfile — `pyproject.toml` has no `lock` file	Root
HIGH	1	CI workflow discards exit codes of critical steps — `.github/workflows/ci.yml` line 39	CI
MEDIUM	3	Duplicated code blocks — 6-line blocks repeated across `cpu_panel.py` and `gpu_panel.py`	Widgets
MEDIUM	8	Broad `except` clauses swallows errors indiscriminately — `cpu.py`, `gpu.py`, `netdisk.py`	Collectors
MEDIUM	3	Deep nesting (max depth 6) — `system.py`, `braille_chart.py`, `setup_wizard.py`	Collectors/Widgets
LOW	1	No `timeout-minutes` set on CI workflow jobs	CI

Fix priority: Add a test suite, commit a lockfile, and fix the CI exit-code discard. The duplicated blocks and broad exception handling are low-effort DRY/refactoring wins.

Entry Points & Control Flow

Execution starts at src/vigil/__main__.py:13 → main(), which launches TerminalInfoApp (defined in app.py). The primary rendering loop is driven by _tick (app.py:288), which reaches 47 functions and is called by nothing else in the repo — it is the root of the update cycle.

Key internal edges (from the call graph of 107 resolved edges):

read → SensorReading x8
collect → safe_read x3
_tick → update_display x2 → update_data x2
compose → BrailleChart x2
push → _update_legend x2

The function with the widest blast radius is _tick, which fans out to every panel update. collect (in collectors) and compose (in app) are the next most connected.

What the Code Touches Outside Itself

7 functions read/write files (config, logs, snapshots, screenshots)
1 function reads/writes a database (session tick log)
1 function makes an outbound network call (webhook alerts on threshold breach)
Shortest out-of-process path: _tick → collect → read_temp [filesystem via self._tpath.read_text().strip]

No background service or telemetry is sent unless a webhook is configured.

File Responsibilities (by routed volume)

File	Functions	Classes	Routes Through	External Effects
`src/vigil/collectors/cpu.py`	17	5	2 other files	reads files, reads database
`src/vigil/app.py`	21	3	1 other file	calls into 17 functions
`src/vigil/session.py`	16	2	3 other files	reads/writes files, outbound network
`src/vigil/collectors/system.py`	6	6	2 other files	—
`src/vigil/widgets/cpu_panel.py`	8	1	3 other files	calls into 2
`src/vigil/collectors/base.py`	2	2	1 other file	reads files
`src/vigil/widgets/gpu_panel.py`	6	1	2 other files	calls into 2
`src/vigil/widgets/status_bar.py`	8	1	2 other files	—
`src/vigil/collectors/netdisk.py`	2	3	1 other file	calls into 3
`src/vigil/config_manager.py`	1	1	1 other file	reads/writes files
`src/vigil/widgets/process_table.py`	6	1	1 other file	calls into 1
`src/vigil/widgets/braille_chart.py`	6	1	1 other file	—
`src/vigil/widgets/setup_wizard.py`	—	—	—	deep nesting detected

Platform Support (per README)

Linux: CPU via hwmon/RAML/estimate; GPU via NVML
Windows: CPU via LibreHardwareMonitor WMI (must run as Admin); GPU via NVML
macOS: CPU estimate only; GPU via NVML if present

Installation (from README + config files)

git clone https://github.com/GIN-SYSTEMS/vigil-tui
cd vigil-tui
pip install .                          # Linux/macOS
pip install ".[windows]"               # Windows (WMI + pywin32)
vigil                                  # launch
vigil --log                            # launch + JSONL tick log

Configuration: config_manager.py loads AppConfig from the config file (path inferred from pyproject.toml/requirements.txt). No environment variables are required at runtime; TDP and kWh price are set via the first-run setup wizard (setup_wizard.py).

Summary

The repository delivers a functional, well-scoped TUI dashboard with real hardware integration. The technical debt is concentrated in three areas: zero test coverage, missing dependency lockfile, and CI exit-code suppression. The duplicated panels and broad exception handlers are straightforward refactors. For a client seeking a single-binary terminal power monitor with hardware sensor fallbacks, this is viable today, but any production deployment should address the HIGH-severity SDLC gaps before shipping.

End of briefing.