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:
@@ -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).
|
||||
Reference in New Issue
Block a user