Files
opencode-system-monitor/README.md
T

15 KiB

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_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:

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.