Files
opencode-system-monitor/README.md
T
David Meincke 7ab4e9fd0b 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.
2026-11-20 13:35:00 +01:00

9.3 KiB

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

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:

%USERPROFILE%\.config\opencode\opencode.jsonc

For example:

{
  "$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:

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:

npm.cmd run smoke

Development

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:

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

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. This is an independent implementation built with the OpenCode plugin SDK.