Files
David Meincke aa8a5f35f6 feat: support Linux system monitoring
Add procfs memory and mount-aware disk collectors, Intel and AMD GPU backends, bounded Intel sampling, portable validation tools, and Linux setup documentation. Bump to 0.2.0 and verify on Windows and Ubuntu 24.04 under WSL2.
2026-11-20 13:51:04 +01:00

298 lines
14 KiB
Markdown

# System Monitor for OpenCode
**Your computer's vital signs, one slash command away.**
A lightweight, on-demand dashboard for **OpenCode Desktop on Windows and Linux** showing disk space, RAM,
CPU utilization, and GPU activity. Inspired by [OpenCode Quota](https://github.com/slkiser/opencode-quota), with
theme-aware cards, utilization bars, and short live-history graphs.
Open `/system` when you need it. Close the dashboard when you're done. **Automatic sampling runs only while
the dashboard is visible.**
## Highlights
- **Disk space:** fixed Windows drives or local Linux filesystems, including available space and reserved blocks.
- **Memory:** physical RAM usage and available memory.
- **CPU:** total utilization, plus a detailed breakdown by logical processor.
- **GPU:** Windows Intel integrated graphics; Linux Intel and AMD collectors with vendor-appropriate memory labels.
- **Live dashboard:** light/dark themes, three-minute history, pause/resume, and adjustable refresh intervals.
- **On demand:** no polling or UI clock timers while the dashboard is closed or its window is hidden.
- **Uncluttered:** no bottom bar, titlebar icon, side tab, or composer pill.
- **Local readings:** no external monitoring service, telemetry, API keys, or model calls for the dashboard.
## Commands
| Command | Result | Where it works |
| --- | --- | --- |
| `/system` | Opens the live graphical dashboard | OpenCode Desktop |
| `/system_status` | Posts a one-time text report without starting a model turn | Desktop, web, and TUI |
The plugin also exposes a `system_monitor_status` tool, so an agent can read the current metrics when asked.
Unlike the dashboard, asking an AI agent about those metrics uses your normal model session.
**Settings → System Monitor** changes the refresh interval. The same control is available inside the dashboard.
## Requirements
| Component | Support |
| --- | --- |
| OpenCode | Built and tested with **2.3.2** |
| Visual dashboard | **Desktop** application |
| Operating system | **Windows 10/11** or **Linux** |
| Windows GPU | Intel integrated graphics with Windows GPU performance counters |
| Linux GPU | Intel through optional `intel_gpu_top`; AMD through `amdgpu` sysfs |
| Development tools | Node.js **22.13+**, npm, and Git |
Windows PowerShell, CIM, and DXGI provide the Windows metrics. Linux uses procfs, filesystem statistics, and DRM
device information. No NVIDIA tools are required or invoked; NVIDIA utilization is not currently implemented.
The full dashboard uses OpenCode's experimental GUI plugin API; the web and TUI clients receive text reports.
If a metric cannot be read, it is shown as unavailable rather than as a misleading `0%`.
## Installation
### 1. Clone and build
Clone the repository from the directory where you keep your projects.
**Linux:**
```bash
git clone https://git.davidmeincke.dk/david/opencode-system-monitor.git
cd opencode-system-monitor
npm ci
npm run build
```
**Windows PowerShell:**
```powershell
git clone https://git.davidmeincke.dk/david/opencode-system-monitor.git
cd opencode-system-monitor
npm.cmd ci
npm.cmd run build
```
Use credentials with access to the repository if it is private. The repository contains the source and
dependency lockfile; `node_modules/` and the generated `dist/` directory are built locally.
### 2. Register the plugin
Add the **absolute path to the cloned directory** to your global OpenCode configuration:
| Platform | Default configuration path |
| --- | --- |
| Linux | `~/.config/opencode/opencode.jsonc` |
| Windows | `%USERPROFILE%\.config\opencode\opencode.jsonc` |
If `XDG_CONFIG_HOME` is set, use `$XDG_CONFIG_HOME/opencode/opencode.jsonc` instead.
For example:
```jsonc
{
"$schema": "https://opencode.ai/config.json",
"plugins": [
// Keep your existing plugin entries here.
"/home/your-name/projects/opencode-system-monitor",
],
}
```
Use the folder path, not the path to an individual JavaScript file. Register it in `opencode.json(c)`,
the configuration used by Desktop plugins. On Windows, a path such as
`"C:/Users/your-name/projects/opencode-system-monitor"` works.
OpenCode reloads configuration automatically. Run **`/system`** to open the dashboard. If the command has
not appeared yet, use **Settings → Extensions → Plugins → Reload** for this plugin.
### Update
From the cloned directory:
```bash
git pull --ff-only
npm ci
npm run build
```
Use `npm.cmd` in PowerShell if `npm` is blocked by its script policy. OpenCode watches the local plugin
and reloads the rebuilt bundle.
### Uninstall
Remove this plugin's directory from the `plugins` array in your global OpenCode configuration.
You can then delete the cloned directory if you no longer need it.
## How sampling works
| Metric | Source | Refresh |
| --- | --- | --- |
| CPU | Deltas between OS CPU-time counters | Selected dashboard interval |
| RAM | Windows OS memory; Linux `/proc/meminfo` `MemAvailable` | Selected dashboard interval |
| Disk | Windows `Win32_LogicalDisk`; Linux `/proc/self/mountinfo` + `statfs` | At most once every **30 seconds** |
| GPU | Windows DXGI/counters; Linux Intel `intel_gpu_top` or AMD sysfs | At most once every **5 seconds** |
The dashboard interval defaults to **3 seconds**, with **2, 3, 5, or 10 seconds** available.
GPU and disk refreshes are rate-limited independently; their next check happens on a dashboard request
after the corresponding interval has elapsed.
### When the dashboard is closed
- Automatic metric requests and the elapsed-time clock are stopped.
- Minimizing or hiding the OpenCode window also stops those timers.
- Opening the dashboard resumes sampling; a long pause starts a fresh CPU measurement interval.
- A request already in progress may finish, but it cannot restart the polling loop.
- `/system_status` and the agent tool can still request an explicit, one-time reading.
The plugin remains loaded in OpenCode with a small amount of state; **no idle polling** does not mean
literally zero memory usage. If another OpenCode window has the dashboard open, that window can still request readings.
### Resource use
CPU reads use Node's OS APIs. Linux RAM reads include reclaimable cache in available memory, rather than treating
all cache as application usage. Windows disk and GPU checks use short-lived, hidden PowerShell processes.
Linux disk and AMD GPU checks read local filesystem data. Intel GPU sampling runs `intel_gpu_top` for roughly
one second, sends it an interrupt, and enforces a three-second hard deadline. No collector invokes `sudo`.
Commands have timeouts and output limits. Concurrent requests share an in-flight collection and recent cached
results across OpenCode project locations.
History contains only the last three minutes in the current window. There is no continuous metrics log or
separate monitoring daemon. Exact CPU and memory overhead has not been benchmarked.
### Linux filesystems
The root filesystem and local mounted filesystems are reported. Bind mounts and btrfs subvolumes sharing the same
filesystem are listed once. Read-only non-root mounts, pseudo-filesystems, snap/loop images, and network mounts are omitted; WSL's local Windows
drive mounts are supported. In a container, the results describe that container's visible mount namespace.
Free space means space available to an ordinary user. Filesystem-reserved blocks are tracked separately, and
percentage used follows `df`: `used / (used + available)`. One unreadable mount does not discard healthy disks.
### GPU support
| Platform / GPU | Collection method | Additional setup |
| --- | --- | --- |
| Windows Intel | DXGI identifies the adapter LUID; Windows counters are combined per engine and the busiest engine is shown | Working Intel driver |
| Linux Intel | `intel_gpu_top -J -p` samples the selected `/dev/dri/cardN`; the busiest physical engine is shown | Install `intel_gpu_top`; the current user needs access to GPU performance counters |
| Linux AMD | `gpu_busy_percent` and `mem_info_vram_*` from the selected DRM device | A driver exposing readable `amdgpu` sysfs counters |
| Headless / unsupported GPU | GPU is explicitly unavailable; other metrics work | None |
On Linux, Intel is preferred when both Intel and AMD are present; otherwise the first AMD card is selected.
The exact DRM card appears in the dashboard. Other adapters' counters are never combined with the selected card.
Intel `i915`/`xe` support depends on the installed GPU-tools version and kernel driver.
For Intel on Debian/Ubuntu, the optional utility is usually available with:
```bash
sudo apt install intel-gpu-tools
```
Other distributions may call the package `igt-gpu-tools`. If performance-counter access is restricted, the
dashboard reports the problem and leaves utilization unavailable. The plugin does not change system permissions.
Windows integrated GPU shared memory is **already included in system RAM usage**. Linux AMD memory is the
driver's VRAM allocation (which can be reserved system RAM on an APU). Linux Intel whole-device memory is
currently unavailable and is not guessed from partial process statistics.
**WSL and VMs:** CPU, RAM, and disk monitoring work, but GPU passthrough does not necessarily expose native DRM/PMU
counters. In that case GPU shows unavailable. Linux CPU/RAM readings describe the Linux environment, not the full
Windows host.
Sizes are displayed in binary units such as **GiB**.
## Troubleshooting
| Symptom | Check |
| --- | --- |
| `/system` is missing | Use OpenCode Desktop, build the plugin, and register its directory in the global `opencode.json(c)`. |
| Desktop lists the plugin but it fails to load | Check **Settings → Extensions → Plugins** and confirm `dist/gui-experimental.cjs` exists. |
| No graphical dashboard in the web client | Use `/system_status`; this version does not add a web GUI. |
| GPU shows unavailable | Check the platform-specific GPU requirements above. This is expected when a VM/WSL instance does not expose native counters. |
| Disk numbers do not change immediately | Disk capacity is cached for up to 30 seconds between checks. |
| Live numbers stop updating | Check the dashboard's **Pause** button and whether the OpenCode window is hidden. |
| A check fails temporarily | The dashboard shows the failure; reopen it or use Refresh to retry. |
To diagnose live collection:
```bash
npm run smoke
# Also require a working hardware GPU reading:
npm run smoke -- --require-gpu
```
The ordinary smoke check validates CPU, RAM and disks, and reports whether GPU telemetry is available.
`--require-gpu` fails if hardware utilization cannot be read.
## Development
### Validation for v0.2.0
| Environment | Verified |
| --- | --- |
| Windows, Node 26.13 | Type-check/build, 24 tests, real CPU/RAM/disk/Intel GPU readings, installed OpenCode RPC and text command |
| Ubuntu 24.04 under WSL2, Node 22.23.5 | Clean dependency install, type-check/build, all 26 tests, real CPU/RAM/disk readings as an unprivileged user |
The two Linux-only process tests verify that Intel sampling exits cleanly and is forcibly terminated if it ignores
the interrupt. Linux GPU parsing, adapter selection, permissions/missing-tool behavior, and AMD sysfs collection are
covered by fixtures. **Native Linux Intel/AMD hardware telemetry has not yet been verified on a physical Linux host**;
WSL on the test machine did not expose the required counters.
### Build and test
```bash
npm ci
npm run verify
```
`verify` type-checks, builds the server and GUI, then runs the automated tests.
| Command | Purpose |
| --- | --- |
| `npm run typecheck` | Type-check the plugin and preview |
| `npm run build` | Compile server modules and the single-file Desktop GUI bundle |
| `npm test` | Run Windows/Linux collectors, adapter isolation, caching, failure, and visibility/polling tests |
| `npm run smoke` | Validate real disk, RAM, and CPU readings and report GPU availability |
| `npm run preview` | Open a development server for the dashboard at `http://127.0.0.1:5098/preview.html` |
Use `npm.cmd` for the same commands in Windows PowerShell when needed.
The preview uses live local readings and includes light/dark, compact-layout, and visibility controls.
It is a development tool and is never started by the installed plugin.
To test an installed plugin against a running OpenCode service:
```bash
node scripts/integration.mjs /path/to/opencode
# Require live hardware GPU telemetry as well:
node scripts/integration.mjs /path/to/opencode --require-gpu
```
On Windows, pass the path to `opencode-cli.exe`. This checks plugin registration, GUI/RPC availability,
disk readings, and the `/system_status` command.
It creates a temporary test session and removes it afterwards.
### Project layout
```text
src/
index.ts Server registration, text command, and agent tool
rpc.ts Dashboard ↔ server contract
metrics.ts On-demand collection and shared caching
linux.ts procfs memory, mounted filesystems, Intel/AMD GPU collectors
windows-gpu.ts Intel DXGI discovery and Windows counter queries
client.ts Visibility-aware polling, pause, and in-memory history
gui.tsx Desktop command, dialog, and settings
dashboard.tsx Cards, utilization bars, charts, and detail view
style.css Theme-aware dashboard styling
tests/ Automated metric and lifecycle checks
scripts/ Smoke test, integration test, and live preview
```
The package is private and not published to npm. The stable plugin ID remains `local-system-monitor`,
which also scopes its saved refresh setting.
## Credits
Dashboard interaction patterns are inspired by [OpenCode Quota](https://github.com/slkiser/opencode-quota).
This is an independent implementation built with the [OpenCode plugin SDK](https://opencode.ai/docs/build/plugins).