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.
225 lines
9.3 KiB
Markdown
225 lines
9.3 KiB
Markdown
# 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).
|