AGENTS.md

Guidance for AI coding agents working in this repository.

What this is

A single-host computer dashboard and task manager: FastAPI (Python ≥ 3.12, managed with uv) backend serving htmx + Chart.js HTML fragments to one browser page. Binds to 127.0.0.1:8501, no auth by design (see the README security section). Tabs: Overview, Disks, Processes, Journal, Services (systemd), Plugins (llama.cpp, sleep, LACT). Licensed under the Unlicense (see LICENSE).

Commands

uv sync                 # install dependencies
uv run python main.py   # run the server on http://127.0.0.1:8501

There is no test suite. Verify changes with:

uv run python -m compileall -q app
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8501/api/overview
# ... other endpoints: /api/disks /api/processes /api/journal /api/services
#                      /api/plugins /api/history
grep -c Traceback /tmp/dash.log

Restarting the dev server

The server usually runs detached in the background. To restart it:

PID=$(pgrep -f "python main\.py" | head -1)
[ -n "$PID" ] && kill "$PID"
setsid nohup uv run python main.py > /tmp/dash.log 2>&1 < /dev/null & disown

Never use pkill -f "uv run python main.py" — the pattern also matches the agent's own shell command line and kills the session.

Architecture

app/collect/* — collectors (cpu/mem/gpu/disks/procs/net/power) read psutil + sysfs; app/sampling.py runs them every DASH_SAMPLE_INTERVAL (default 2 s) into an in-memory ring buffer (app/state.py).
app/routers/* — each tab endpoint is an idempotent GET returning an htmx HTML fragment; templates live in templates/ and self-poll via hx-get + hx-trigger="every Ns" + hx-swap="outerHTML".
templates/*.html auto-reload on file change — no restart needed for template-only edits. Python changes require a restart.
app/systemd/units.py — systemd unit listing/detail/actions; app/journal.py — journalctl -o export parser with cursors.
app/plugins/ — base.Plugin (optional open/close lifecycle hooks run from app lifespan) + llamacpp plugin (talks to a router-mode llama-server on port 8080) + sleep plugin (lists block-mode systemd-inhibit locks; holds its own sleep lock via a systemd-inhibit ... sleep infinity child while the UI switch is on, reaps stale locks by who marker on startup)
- lact plugin (shells out to lact cli: per-GPU profile dropdown with set/reload, active profile polled every 5 s, GPU names shortened with app/collect/gpu.py:shorten like the overview card).

Conventions

Google-style docstrings for every function and class: one-line imperative summary, an Args: section for each parameter, and Returns:/Raises: where non-obvious. Complex functions (parsers, subprocess wrappers, anything touching the pitfalls below) get extra prose explaining the behaviour, not just the signature.
Inline comments are allowed only for Sample dataclass field docs.
basedpyright is configured as linter, use with uvx.
Match surrounding style; keep functions small and typed where the codebase already is.
Keep polling endpoints cheap: collectors may cache lookups (unit names, enabled-state maps, SSID, temperature paths) with short TTLs.

Hard-won pitfalls

Jinja autoescape renders ↓ as literal text — use literal unicode (e.g. ↓) in templates.
journalctl -o export output contains NUL bytes (grep treats it as binary); journalctl rejects negated matches (!/!=) — filter entries in Python instead.
psutil gotchas: there is no psutil.AF_INET (use socket); net_if_addrs() / net_if_stats() take no arguments; sensors_battery().power_plugged can be None — use /sys/class/power_supply/* (type/capacity/status/online) for battery + AC state.
iw dev <if> link prints SSID: name unquoted; the working regex is SSID:\s+(\S.*) (a $ anchor fails without MULTILINE).
/api/history window-averages the ring buffer down to at most chart_max_points (default 200) points, emitting {avg, min, max} per key, and pads each of the three arrays with null for windows missing a key so they stay aligned with the timestamps — keep that behaviour if you touch it.
AMD sysfs: GPU busy/VRAM/temp under /sys/class/drm/card*/device (+ hwmon), CPU temp from the k10temp hwmon (fallback acpitz thermal zone), both in millidegrees.

4.4 KiB Raw Blame History