# 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).