316 lines
15 KiB
Markdown
316 lines
15 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.
|
|
|
|
### Hosted OpenCode (Docker / Portainer)
|
|
|
|
Register the built plugin in the **server's persistent global config**. Use a package directory the running
|
|
OpenCode process can read, containing `package.json`, `dist/`, and the installed runtime dependencies.
|
|
For a container with an isolated filesystem, mount that directory read-only and use its **container path**
|
|
in `plugins`. For a runtime that starts in the host filesystem, use the host path directly.
|
|
|
|
In the hosted web composer, select `/system_status` and send it to see the server's readings. It works without
|
|
a model request. The `/system` graphical dashboard is available in Desktop only.
|
|
|
|
### 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 |
|
|
| Native Linux, Minisforum Ryzen 9 PRO 8945HS / Radeon 780M, hosted OpenCode 2.3.2 | All 26 tests, GPU-required smoke check, live snapshot RPC and agent tool, and `/system_status` in the authenticated web composer. RAM and VRAM totals matched procfs/sysfs. |
|
|
|
|
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 AMD utilization and VRAM were also verified on the physical Minisforum.
|
|
Native Intel hardware telemetry on Linux remains fixture-tested; 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.
|
|
|
|
For a hosted service, pass its endpoint explicitly to avoid local service discovery. Set `OPENCODE_PASSWORD`
|
|
in the test environment if the server requires authentication. Use the absolute project directory **on the server**:
|
|
|
|
```bash
|
|
node scripts/integration.mjs /path/to/opencode --server https://opencode.example.com --directory /srv/projects/example --require-gpu
|
|
```
|
|
|
|
### 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).
|