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, 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:
git clone https://git.davidmeincke.dk/david/opencode-system-monitor.git
cd opencode-system-monitor
npm ci
npm run build
Windows 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:
{
"$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:
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_statusand 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:
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:
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
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:
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:
node scripts/integration.mjs /path/to/opencode --server https://opencode.example.com --directory /srv/projects/example --require-gpu
Project layout
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. This is an independent implementation built with the OpenCode plugin SDK.