Show the local llama.cpp router's state in opencode with ocmon

Steps#

1. Install ocmon at the tested version. The source is public at gitlab.com/myrants-oss/ocmon (MIT), and go install fetches it from the Go module proxy, so there is nothing to clone. It is one main.go with no dependencies outside the standard library. The version string pins commit f067f45 (Scope, Version):

   go install gitlab.com/myrants-oss/ocmon@v0.0.0-20261021182238-f067f458af51
   

   Without GOBIN the binary goes to ~/go/bin. On 2026-10-21 @latest still resolved to this version; I set GOBIN to keep it out of my PATH for the test:

   $ GOBIN="$PWD/bin" go install gitlab.com/myrants-oss/ocmon@latest
   $ go version -m bin/ocmon | head -3
   bin/ocmon: go1.26.9-X:nodwarf5
   	path	gitlab.com/myrants-oss/ocmon
   	mod	gitlab.com/myrants-oss/ocmon	v0.0.0-20261021182238-f067f458af51	h1:ruhYlOpc4JPqKYVhtGPKsxWarAhRMrV0c4OZqgbGh0A=
   

   Expected: go install prints nothing, or one go: downloading … line on the first fetch, and go version -m names the module with the v0.0.0-20261021182238-f067f458af51 version.

2. Check the flags.

   $ bin/ocmon -h
   Usage of bin/ocmon:
     -dev string
       	amdgpu sysfs device dir (env OCMON_DEV; default: first card with gpu_busy_percent) (default "/sys/class/drm/card1/device")
     -i duration
       	refresh interval (default 1s)
     -json
       	print one JSON object (class, line, side, detail) and exit
     -log string
       	router log file (env OCMON_LOG); without it only model states are shown
     -url string
       	router base URL (env OCMON_URL) (default "http://127.0.0.1:8080")
     -waybar
       	print one JSON line for a waybar custom module and exit
   

   Flags win over the OCMON_* variables. The README.md in the module directory (step 5) has the full table; the README on the repository page describes the later version. What each part reads:

   • -url: GET <url>/models on every refresh, and GET <url>/slots?model=<name>&autoload=false only while the log shows a running request (for the live generated-token count).
   • -log: the last 1 MiB of the log on every refresh.
   • -dev: gpu_busy_percent, mem_info_gtt_used, mem_info_vram_used. A missing file prints ?. The busy figure is one reading per refresh, not an average.
   • -waybar prints {"class","text","tooltip"} with an empty text when the router is down; -json prints {"class","line","side","detail"}, where side holds the short lines for opencode's sidebar.

   Expected: the six flags above, with the env names in the help text.

3. Run it once in JSON mode.

   <OCMON> -json -log <ROUTER_LOG>
   

   With no router on port 8080 (re-run 2026-11-05 on the 780M box):

   $ bin/ocmon -json
   {"class":"down","detail":["GPU 27%  GTT 1772 MiB  VRAM 475 MiB  40.1 W  CPU 75°C  GPU 56°C","router: Get \"http://127.0.0.1:8080/models\": dial tcp 127.0.0.1:8080: connect: connection refused"],"line":"router down","side":null}
   

   Expected: one JSON line whose class is one of the states below. error with router up, log unreadable means the -log path is wrong (Failure modes, row 2).

   class	When	line printed
   down	GET /models fails	router down
   error	log unreadable, or the log shows a load error and no model loaded for the current instance	router up, log unreadable / <model> FAILED to load (see router.log)
   idle	every model is unloaded	idle, no model loaded
   loading	/models says loading	ornith-35b loading…
   sleeping	/models says sleeping	ornith-35b sleeping (memory freed)
   loaded	loaded, but no -log, or the newest instance in the log is another model	ornith-35b loaded
   prompt	request running, prompt not finished	ornith-35b reading prompt ██░░░░░░░░░░░░░░░░░░ 11% 2048/18618 tok 145 t/s · ~114 s left
   gen	request running, prompt done	<model> generating <n> tok <rate> t/s (… instead of the rate on the first sample)
   ready	loaded, no request running	ornith-35b ready last: prompt 21 tok @ 11 t/s, gen 263 tok @ 17.7 t/s, ctx 18353

   The line values with a model name come from a replay of my router log through this binary (Field notes, 21:24); that output was not kept, and each value matches the format string in the source. idle, gen and the load-failure text are from the source and were not observed. On a load failure the sidebar's second line is the fixed text see serve/router.log, whatever your log path is.

   The prompt total is n_tokens / progress from the newest progress line, and the ETA is the remaining tokens divided by the running rate. llama.cpp prints progress with two decimals, so both are estimates (Field notes: 114 s shown, about 139 s real).

4. Run the full-screen view.

   <OCMON> -log <ROUTER_LOG>
   

   One frame with no router on port 8080 (re-run 2026-11-05 on the 780M box):

   ocmon  11:05:12   (ctrl-c to quit)
   
     router down
   
     GPU 27%  GTT 1772 MiB  VRAM 475 MiB  46.9 W  CPU 75°C  GPU 56°C
     router: Get "http://127.0.0.1:8080/models": dial tcp 127.0.0.1:8080: connect: connection refused
   

   Expected: the screen redraws every -i (1 s). The line under the clock is the same line as in JSON mode; below it are the hardware line and either the router error or the model list (models: <id>:<status> …).

   GotchaCtrl-C leaves the cursor hidden

   ocmon hides the cursor and restores it in a deferred call, which does not run when Ctrl-C or SIGTERM kills the process. Run tput cnorm afterwards to get the cursor back.

5. Get the plugin file. The opencode plugin is opencode-plugin/llm-status.tsx in the module. Commit f067f45 is no longer on the repository's branch, so take it from the same module version as the binary:

   go mod download -json gitlab.com/myrants-oss/ocmon@v0.0.0-20261021182238-f067f458af51
   

   It prints a JSON object whose "Dir" is the module's directory in Go's module cache (read-only). Copy the plugin out of it, with <DIR> = that Dir value:

   mkdir -p <SRC>/opencode-plugin
   cp <DIR>/opencode-plugin/llm-status.tsx <SRC>/opencode-plugin/
   

   Expected: <SRC>/opencode-plugin/llm-status.tsx exists, from the same version as the binary.

   What it does: runs <bin> -json <args…> every intervalMs (skipping a tick while the previous call still runs, 3 s timeout), fills two opencode slots, sidebar_content (session view) and home_footer (home screen), and hides both when ocmon fails or reports down. It raises a toast on three transitions: loading to ready, any state to sleeping, any state to error. opencode loads the .tsx file as it is; there is no build step.

6. Write <TUI_JSON> with the plugin's absolute path and its options. [UNVERIFIED: this options form was not run in opencode on this box.]

   {
     "$schema": "https://opencode.ai/tui.json",
     "plugin": [
       ["<SRC>/opencode-plugin/llm-status.tsx",
        { "bin": "<OCMON>", "args": ["-log", "<ROUTER_LOG>"], "intervalMs": 1000 }]
     ]
   }
   

   bin defaults to ocmon from opencode's PATH; an absolute path avoids depending on it. args go after -json; add "-url", "…" if the router is not on 127.0.0.1:8080. intervalMs below 250 is ignored (1000 is used).

7. Pass that file to opencode from your wrapper only. The opencode call in oc must carry OPENCODE_TUI_CONFIG=<TUI_JSON>. The prerequisite manual's oc already has the line; if your wrapper does not, add it. The end of my oc:

   OPENCODE_DISABLE_CLAUDE_CODE=$claude_off \
   OPENCODE_TUI_CONFIG="$ROOT/serve/opencode-tui/tui.json" \
   OPENCODE_CONFIG="$ROOT/serve/opencode-local.json" opencode "$@"
   

   opencode's docs say OPENCODE_TUI_CONFIG points to a custom TUI config file. [UNVERIFIED: that opencode 1.19.3 merges it with the global tui.json, so global TUI settings still apply, was not checked against its source.] A plain opencode (cloud sessions) does not get the variable and shows no panel.

8. Start oc and send a prompt. [UNVERIFIED: with the public plugin and options form; see Scope.] Expected: the home screen shows local LLM: <line> at the bottom, and the session sidebar shows a Local LLM section (see Verify).

9. Optional: add a waybar module. [UNVERIFIED: not run on this box; there is no ocmon module in my waybar config.] Built from the waybar 0.15.0 waybar-custom(5) man page. Add "custom/ocmon" to one of the modules-* lists and define it:

   "custom/ocmon": {
     "exec": "<OCMON> -waybar -log <ROUTER_LOG>",
     "return-type": "json",
     "interval": 1,
     "hide-empty-text": true
   }
   

   class becomes a CSS class, so #custom-ocmon.prompt, #custom-ocmon.error and the other class names from step 3 can be styled in style.css. -waybar output with no router on port 8080 (re-run 2026-11-05 on the 780M box):

   $ bin/ocmon -waybar
   {"class":"down","text":"","tooltip":"GPU 27%  GTT 1772 MiB  VRAM 475 MiB  46.4 W  CPU 75°C  GPU 56°C\nrouter: Get \"http://127.0.0.1:8080/models\": dial tcp 127.0.0.1:8080: connect: connection refused"}