Skip to content

feat(os-vitals): Linux support and the fallback for other systems - #8

Merged
pblobp merged 9 commits into
mainfrom
feat/os-vitals-linux
Nov 18, 2026
Merged

pblobp merged 9 commits into
mainfrom
feat/os-vitals-linux

Conversation

@pblobp

@pblobp pblobp commented Nov 18, 2026

Copy link
Copy Markdown
Owner

What changed and why

OS Vitals now works on Linux, and degrades cleanly on Windows and other systems. Nothing is released by this change.

  • Linux: the worker reads /proc and /sys directly, with no ps: memory and pressure, processes (CPU from tick deltas, names from the command line because the kernel's own name is cut at 15 characters and reads MainThread for every Node process), network, disk activity, volumes, AMD GPUs and the battery with its power draw. NVIDIA GPUs go through nvidia-smi. Quitting a process uses the same guards, with identity from the start time in stat. Kernel threads are listed but never offered.
  • Fallback: Windows and other systems get CPU and memory from node:os, and the panel says so once.
  • Cost: disk and GPU are read on every second tick outside their own views, and energy every 10 seconds. The Overview now costs about 2.3% of one core (was 3.1%), and the Energy view about 8% while open (was 15%).
  • Fix, with a test that failed first: a style added for the detail views also matched the process table's rows, which collapsed when a filter was set. That bug is on main since the previous pull request and is fixed here.

Plugin

os-vitals

Access changes

No change to capabilities, commands or panels. Two program paths are added to the allowlist in policy/os-vitals.json, for the same program:

  • /usr/bin/nvidia-smi and /usr/local/bin/nvidia-smi: NVIDIA GPU utilization and memory on Linux, probed once at start.

Network: none.

Tests

  • npm run check: formatting, policy, catalog and versions pass; 143 of 143 script tests pass.
  • orca plugin validate plugins/os-vitals --json: valid.
  • orca plugin test plugins/os-vitals --json: 20 of 20 worker tests pass.
  • node --test 'tests/os-vitals/**/*.test.ts': 259 of 259 pass, against cleaned fixture trees for a laptop, a Debian container and Alpine.
  • Real Linux, in node:24-bookworm and node:24-alpine containers: every unit test and the smoke test pass. With the host's process list visible, it read 214 processes and flagged 200 kernel threads.
  • This pull request's CI runs the extended Linux smoke test on ubuntu-24.04 under strace.

Not verified: NVIDIA and AMD readings on real hardware and a real battery on Linux (fixtures only), x86_64 hardware outside CI, and the panel inside Orca on Linux. The Windows memory reading follows Node's documented behaviour and CI's range check; it was not inspected on a Windows machine.

Screenshots

Reviewed locally from Orca on macOS (dark) and from the harness, including Linux and Windows scenarios. Not attached: the CLI cannot upload images, and the repository does not commit screenshots.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EWVANCgSt8W3VxxxZyAyoD

pblobp and others added 9 commits November 17, 2026 18:35
A worker that samples CPU from node:os, an HTML panel with the
Overview CPU card, a status bar item, and the command that opens the
panel through Orca's CLI. The manifest already declares the final
access: two capabilities, one panel, one command, one status bar item.

Unit tests and the smoke test live outside the plugin folder, so they
are not installed.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_01EWVANCgSt8W3VxxxZyAyoD
The worker reads memory from vm_stat and sysctl, the process list from
ps, and core kinds from ioreg. Process CPU comes from CPU time between
two readings. The panel gains the memory card, the top processes card,
and a sortable, filterable process table with a details drawer.

Processes are read only while a view shows them. Measured cost is
about 1.2% of one core with the Overview open and 0.16% in the
background.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_01EWVANCgSt8W3VxxxZyAyoD
The worker sends the signal only after reading the process again and
matching its start time, owner and name. It refuses the worker's own
family, anything inside Orca's app bundle, and a protected set of
system and Orca processes. The panel confirms in a dialog, and offers
force quit when the process is still running five seconds later.

Also fixes the ancestor walk, which stopped at the worker's parent,
and re-sends a status bar update that Orca refused.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_01EWVANCgSt8W3VxxxZyAyoD
CodeQL flagged the development server for returning an error's text
to the client. It now logs the error and answers with a fixed message.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_01EWVANCgSt8W3VxxxZyAyoD
The worker reads network rates from netstat, disk activity and the GPU
from ioreg, volumes from df, the battery and sleep blockers from pmset,
and per-process energy impact from top. Energy is read only while its
view is open. Rates are counted per interface and per drive, so a
counter reset reads as zero.

The Overview gains four cards. Each card opens a detail view, and every
line chart has a crosshair and tooltip for pointer and keyboard.

The Orca rule in the protected set no longer catches unrelated apps
whose names merely start with the same letters.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_01EWVANCgSt8W3VxxxZyAyoD
Linux reads /proc and /sys directly: memory with pressure, processes
with CPU from tick deltas, network, disk, volumes, AMD and NVIDIA GPUs
and the battery. Quitting works there through the same guards, and
kernel threads are never offered. Windows and other systems get CPU
and memory, and the panel says so once.

Disk and GPU are now read on every second tick outside their own
views, and energy every 10 seconds, which lowers the cost of the
Overview and of the Energy view.

Fixes the process table, whose rows collapsed when a filter was set.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_01EWVANCgSt8W3VxxxZyAyoD
@pblobp
pblobp merged commit 4d5296e into main Nov 18, 2026
11 checks passed
@pblobp
pblobp deleted the feat/os-vitals-linux branch November 18, 2026 11:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant