Imported from capyBearista/opencode-plugins (
packages/opencode-ram-monitor/AGENTS.md). Install upstream withnpx skills add capyBearista/opencode-plugins --skill opencode-ram-monitor. Copyright stays with the author.
opencode-ram-monitor — OpenCode plugin
Technology: TypeScript / OpenCode Plugin / OpenTUI
Entry Points: src/server.ts, src/sidebar.tsx
Parent Context: This extends ../../AGENTS.md
Compatibility: V1-only (releaseClass: v1, latest channel) — no V2 port in this release.
This package is a dual server/TUI plugin. The server side registers /ram and injects process-tree output into the session. The TUI side renders a live sidebar widget with lightweight RAM polling.
Quick Reference
| Script | Purpose |
|---|---|
bun run check |
Lint and format (Biome) |
bun run lint |
Validate without modifying |
bun run ci |
CI mode (non-mutating) |
bun run typecheck |
Type check |
bun test |
Run tests |
bun run build |
Build server/TUI outputs and declarations |
Development Commands
This Package
# From package directory bun run build bun test bun run typecheck bun run lint
From Root
bun --filter @capybearista/opencode-ram-monitor build bun --filter @capybearista/opencode-ram-monitor test
Pre-PR Checklist
bun --filter @capybearista/opencode-ram-monitor typecheck && \ bun --filter @capybearista/opencode-ram-monitor lint && \ bun --filter @capybearista/opencode-ram-monitor test
Code Style
- Zero comments by default. Only add when code isn't self-explanatory.
- No
console.log. Use the debug helpers insrc/debug.tsso failures can be correlated without polluting chat output. - Colocate tests with source files (
src/index.test.ts). - Imports: builtins first, then external, then relative.
Architecture
Directory Structure
src/ ├── index.ts # Server barrel export ├── server.ts # Registers /ram and injects command output ├── sidebar.tsx # Sidebar widget and polling lifecycle ├── memory.ts # Heavy/lightweight RAM collection helpers ├── snapshot.ts # Cache for repeated process snapshots ├── sidebar-config.ts # Widget config loading and validation └── debug.ts # File-backed debug logging
Core (understand these first)
src/server.ts— registers the/ramcommand and short-circuits normal command execution after injecting raw output back into the sessionsrc/sidebar.tsx— TUI widget with recursivesetTimeoutpolling, theme-aware rendering, and cleanup on unmountsrc/memory.ts— process inspection logic; this is where OS-specific behavior and performance tradeoffs livesrc/sidebar-config.ts— config discovery and fallback behavior for widget refresh intervals
Build
This package is a split-output plugin:
tsc --project tsconfig.build.json --emitDeclarationOnlyemits type declarationsbun buildcompiles each runtime entrypoint separately for server and TUI usepackage.jsonpublishes separate./serverand./tuiexports and declaresoc-plugin: ["server", "tui"]
Gotchas
- Do not introduce top-level async work in
src/sidebar.tsx; keep polling startup insideonMount. - Use recursive
setTimeout, notsetInterval, so RAM probes cannot overlap. - Any change to RAM collection should be validated on the target OS pattern documented in
docs/opencode-plugin-ipc-and-os-patterns.md. - Command injection failures must fail clearly;
/ramshould not silently swallow output or leave the session hanging.
Testing Guidelines
- Location: colocated
- Framework: bun test
- Running Tests:
bun test - Runtime smoke: verify both the
./serverand./tuiexports load in OpenCode and that the sidebar widget still renders without IPC startup regressions
License
MPL-2.0