feat: add on-demand OpenCode system monitor

Add a Desktop dashboard and text status command for disk space, RAM, CPU and Intel integrated graphics. Include visibility-driven sampling, tests, development tooling, and installation documentation.
This commit is contained in:
David Meincke
2026-11-20 13:35:00 +01:00
commit 7ab4e9fd0b
26 changed files with 6862 additions and 0 deletions
+224
View File
@@ -0,0 +1,224 @@
# System Monitor for OpenCode
**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
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:** free, used, and total capacity for each fixed Windows drive.
- **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.
- **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** |
| GPU | Intel integrated graphics with Windows GPU performance counters |
| 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.
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
Run in PowerShell, from the directory where you keep your projects:
```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:
```text
%USERPROFILE%\.config\opencode\opencode.jsonc
```
For example:
```jsonc
{
"$schema": "https://opencode.ai/config.json",
"plugins": [
// Keep your existing plugin entries here.
"C:/Users/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.
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:
```powershell
git pull --ff-only
npm.cmd ci
npm.cmd run build
```
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 | 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** |
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 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
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
DXGI identifies the Intel adapter's **LUID**, the identifier used by Windows' GPU performance counters.
Only counters for that adapter are included:
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.
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.
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 | Confirm Intel graphics is enabled and its driver exposes Windows GPU-engine 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:
```powershell
npm.cmd run smoke
```
## Development
```powershell
npm.cmd ci
npm.cmd 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` |
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"
```
This checks plugin registration, GUI/RPC availability, Intel 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
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).