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.
This commit is contained in:
@@ -2,8 +2,8 @@
|
||||
|
||||
**Your computer's vital signs, one slash command away.**
|
||||
|
||||
A lightweight, on-demand dashboard for **OpenCode Desktop** showing disk space, RAM, CPU utilization, and
|
||||
Intel integrated graphics. Inspired by [OpenCode Quota](https://github.com/slkiser/opencode-quota), with
|
||||
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
|
||||
@@ -11,10 +11,10 @@ the dashboard is visible.**
|
||||
|
||||
## Highlights
|
||||
|
||||
- **Disk space:** free, used, and total capacity for each fixed Windows drive.
|
||||
- **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.
|
||||
- **Intel integrated GPU:** utilization and shared system-memory usage, matched to the actual Intel adapter.
|
||||
- **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.
|
||||
@@ -38,11 +38,13 @@ Unlike the dashboard, asking an AI agent about those metrics uses your normal mo
|
||||
| --- | --- |
|
||||
| OpenCode | Built and tested with **2.3.2** |
|
||||
| Visual dashboard | **Desktop** application |
|
||||
| Operating system | **Windows 10/11** |
|
||||
| GPU | Intel integrated graphics with Windows GPU performance counters |
|
||||
| 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. No NVIDIA tools are required or invoked.
|
||||
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%`.
|
||||
|
||||
@@ -50,7 +52,18 @@ If a metric cannot be read, it is shown as unavailable rather than as a misleadi
|
||||
|
||||
### 1. Clone and build
|
||||
|
||||
Run in PowerShell, from the directory where you keep your projects:
|
||||
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
|
||||
@@ -66,9 +79,12 @@ dependency lockfile; `node_modules/` and the generated `dist/` directory are bui
|
||||
|
||||
Add the **absolute path to the cloned directory** to your global OpenCode configuration:
|
||||
|
||||
```text
|
||||
%USERPROFILE%\.config\opencode\opencode.jsonc
|
||||
```
|
||||
| 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:
|
||||
|
||||
@@ -77,13 +93,14 @@ For example:
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"plugins": [
|
||||
// Keep your existing plugin entries here.
|
||||
"C:/Users/your-name/projects/opencode-system-monitor",
|
||||
"/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.
|
||||
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.
|
||||
@@ -92,13 +109,14 @@ not appeared yet, use **Settings → Extensions → Plugins → Reload** for thi
|
||||
|
||||
From the cloned directory:
|
||||
|
||||
```powershell
|
||||
```bash
|
||||
git pull --ff-only
|
||||
npm.cmd ci
|
||||
npm.cmd run build
|
||||
npm ci
|
||||
npm run build
|
||||
```
|
||||
|
||||
OpenCode watches the local plugin and reloads the rebuilt bundle.
|
||||
Use `npm.cmd` in PowerShell if `npm` is blocked by its script policy. OpenCode watches the local plugin
|
||||
and reloads the rebuilt bundle.
|
||||
|
||||
### Uninstall
|
||||
|
||||
@@ -110,9 +128,9 @@ You can then delete the cloned directory if you no longer need it.
|
||||
| Metric | Source | Refresh |
|
||||
| --- | --- | --- |
|
||||
| CPU | Deltas between OS CPU-time counters | Selected dashboard interval |
|
||||
| RAM | Physical memory total and available memory | Selected dashboard interval |
|
||||
| Disk | `Win32_LogicalDisk`, fixed drives only | At most once every **30 seconds** |
|
||||
| Intel GPU | DXGI adapter identity + Windows GPU engine and memory counters | At most once every **5 seconds** |
|
||||
| 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
|
||||
@@ -131,24 +149,54 @@ literally zero memory usage. If another OpenCode window has the dashboard open,
|
||||
|
||||
### Resource use
|
||||
|
||||
CPU and RAM reads use Node's OS APIs. Windows disk and GPU checks use short-lived, hidden PowerShell processes.
|
||||
These commands have timeouts and output limits. Concurrent requests share an in-flight collection and recent cached
|
||||
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.
|
||||
|
||||
### What the GPU number means
|
||||
### Linux filesystems
|
||||
|
||||
DXGI identifies the Intel adapter's **LUID**, the identifier used by Windows' GPU performance counters.
|
||||
Only counters for that adapter are included:
|
||||
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.
|
||||
|
||||
1. Sum process utilization for each individual GPU engine.
|
||||
2. Display the busiest engine's utilization.
|
||||
3. Read shared memory usage for the same adapter.
|
||||
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.
|
||||
|
||||
This avoids adding unrelated GPUs together or depending on adapter ordering. Integrated graphics borrows
|
||||
system RAM; its shared-memory figure is **already included in system RAM usage**, not additional dedicated VRAM.
|
||||
### 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**.
|
||||
|
||||
@@ -159,44 +207,68 @@ Sizes are displayed in binary units such as **GiB**.
|
||||
| `/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 | Confirm Intel graphics is enabled and its driver exposes Windows GPU-engine counters. |
|
||||
| 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 on a Windows machine with Intel graphics:
|
||||
To diagnose live collection:
|
||||
|
||||
```powershell
|
||||
npm.cmd run smoke
|
||||
```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
|
||||
|
||||
```powershell
|
||||
npm.cmd ci
|
||||
npm.cmd run verify
|
||||
### 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.cmd run typecheck` | Type-check the plugin and preview |
|
||||
| `npm.cmd run build` | Compile server modules and the single-file Desktop GUI bundle |
|
||||
| `npm.cmd test` | Run metric parsing, adapter isolation, caching, failure, and visibility/polling tests |
|
||||
| `npm.cmd run smoke` | Validate real disk, RAM, CPU, and Intel GPU readings on this machine |
|
||||
| `npm.cmd run preview` | Open a development server for the dashboard at `http://127.0.0.1:5098/preview.html` |
|
||||
| `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:
|
||||
|
||||
```powershell
|
||||
node scripts/integration.mjs "C:\path\to\opencode-cli.exe"
|
||||
```bash
|
||||
node scripts/integration.mjs /path/to/opencode
|
||||
# Require live hardware GPU telemetry as well:
|
||||
node scripts/integration.mjs /path/to/opencode --require-gpu
|
||||
```
|
||||
|
||||
This checks plugin registration, GUI/RPC availability, Intel readings, and the `/system_status` command.
|
||||
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
|
||||
@@ -206,6 +278,7 @@ 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
|
||||
|
||||
Reference in New Issue
Block a user