@ross/activity-indicator (1.0.0-alpha.3)
Installation
@ross:registry=npm install @ross/activity-indicator@1.0.0-alpha.3"@ross/activity-indicator": "1.0.0-alpha.3"About this package
🦊 Activity Indicator
Real-time polar scatter visualization of system thread activity. Served publicly at ross.realyhd.me.
What You See
Each dot is one Linux thread (TID) discovered via /proc/<pid>/task/. Three dots per thread group form a visual cluster:
- 🔵 Blue dot (CPU) — angle = RAM rank, radial distance = avg CPU% of that thread
- 🟣 Purple dot (IO) — same angle −3°, radial distance = I/O throughput (KB/s)
- 🟢 Emerald dot (RAM) — same angle +3°, radial distance = RSS / total system RAM
- Grey dots — idle threads (CPU < 2%, low IO, low RAM)
- Faint connecting lines — link the three dots belonging to the same thread group
Reference rings mark 25%, 50%, 75%, and 100% of each metric's scale.
Data Pipeline
┌──────────────────────────┐
│ /proc/<pid>/task/<tid> │ ← individual thread stats (never aggregate)
│ /proc/<pid>/status │
│ /proc/<pid>/io │
│ /proc/loadavg │
│ /proc/meminfo │
└──────────┬───────────────┘
│ 100ms polling
▼
┌─────────────────────────────────────┐
│ Backend (Node.js :2048) │
│ │
│ - Discovers all non-kernel TIDs │
│ - Computes CPU% from /proc/<tid>/stat│
│ - Reads VmRSS, rchar/wchar │
│ - Server-side 5-sample ring buffer │
│ (500ms trailing average) │
│ - Sends pre-averaged SSE stream │
└────────────────┬────────────────────┘
│ SSE (Server-Sent Events)
▼
┌─────────────────────────────────────┐
│ Frontend (SvelteKit SPA) │
│ - Receives averaged metrics │
│ - Per-PID interpolation (0.08 lerp)│
│ - Canvas rendering @ 60fps │
│ - "Ross" label at center │
└─────────────────────────────────────┘
Key design decisions
- No PID binning — each Linux thread is a distinct dot
- No aggregate CPU — skipped group leaders to avoid >100% artifacts
- Server-side averaging — fresh clients get smooth data immediately
- No process names exposed — only PIDs and numeric metrics in public data
- No authentication — intentional; contains no sensitive information
- Server-side singleton — metrics polled once per interval, broadcast to all clients; operations do not scale with client count
Ignored processes
The activity indicator's own threads are excluded by default (detected via process.pid + /proc/<pid>/task/).
Additional processes can be excluded by setting the ACTIVITY_IGNORED environment variable to a comma-separated list of regex patterns matched against /proc/<tid>/cmdline:
ACTIVITY_IGNORED="python,sshd,nginx"
Deployment
On the host
# Managed as a systemd user service
activity-indicator status # check it
activity-indicator restart # bounce it
journalctl --user -u activity-indicator -f # tail logs
Port & routing
The service binds to 0.0.0.0:2048. A Cloudflare tunnel at ross.realyhd.me routes traffic to it. Future sites on this host should use port 2048 with a reverse proxy (e.g., nginx) delegating by path.
Package manager
The package is published to the Forgejo NPM registry at git.reslate.solutions and installed globally via npm.
Development
Prerequisites
- Node.js ≥ 22 (via conda-forge / micromamba)
- Linux (reads
/proc)
Setup
# Create conda environment (first time only)
micromamba create -n activity-indicator -f environment.yml
# Install dependencies
npm install
npm run dev # dev server
npm run build # production build
npm test # run tests
Commit Convention
Conventional Commits enforced by commitlint + husky pre-commit hooks.
Types: feat, fix, chore, docs, style, refactor, perf, test, ci, build, revert.
CI
Forgejo Actions at git.reslate.solutions. Pipeline: lint → typecheck → test → build → release.
The alpha branch pushes pre-releases via semantic-release (prerelease: "alpha").
Security
- Read-only — backend only reads
/proc, never writes - No labels — process names stripped from all public endpoints
- No credentials — no auth required or provided
- Public-safe — PIDs are ephemeral, non-sensitive identifiers
License
MIT — Reslate Solutions
Dependencies
Development dependencies
| ID | Version |
|---|---|
| @commitlint/cli | ^19.0.0 |
| @commitlint/config-conventional | ^19.0.0 |
| @ross/semantic-release-forgejo | ^1.0.0 |
| @sveltejs/adapter-node | ^5.0.0 |
| @sveltejs/kit | ^2.0.0 |
| @sveltejs/vite-plugin-svelte | ^5.0.0 |
| @types/node | ^22.19.18 |
| conventional-changelog-conventionalcommits | ^8.0.0 |
| eslint | ^9.0.0 |
| globals | ^17.6.0 |
| husky | ^9.0.0 |
| prettier | ^3.4.0 |
| prettier-plugin-svelte | ^3.5.1 |
| semantic-release | ^25.0.0 |
| svelte | ^5.0.0 |
| svelte-check | ^4.0.0 |
| typescript | ^5.7.0 |
| vite | ^6.0.0 |