RuView/docs/adr/ADR-377-ruview-live-claude-code-mod.md

# ADR-377: `ruview-live` — a Claude Code mod shipped inside `@ruvnet/ruview`

- **Status**: proposed
- **Date**: 2026-10-01
- **Deciders**: rUv (requested integration into the npm package); RuView maintainers
- **Tags**: claude-code, mods, function-hooks, ui, npm, least-authority
- **Related**: ADR-373 (device access), ADR-375 (MCP Apps console, terminal UI),
  ADR-376 (umbrella package); Claude Code mods (function hooks): the
  claude-code issue 91870 and the `mods/` built-ins (`diff` is the closest
  analogue)

## Context

Claude Code mods are plugins whose behaviour is a function-hooks module: one
`register(on, options)` that hooks engine events as `($, e, next)`. They can:
- register slash commands;
- open panes beside the transcript and draw them with the surface's elements;
- set a status line;
- run processes through `$.process.run`.

That fits RuView's goal of putting the live state of the sensors where an
operator or agent already works.

RuView already has:
- a read-only CLI with `--json` results (ADR-373, ADR-375);
- an MCP server and the ChatGPT/MCP Apps console;
- a plugin marketplace in this repository.

## Decision

1. **Ship a mod, `ruview-live`, inside `@ruvnet/ruview`** (`mod/`, packaged
   files `mod/.claude-plugin/`, `mod/hooks/`).
   - It is listed in the repository marketplace as `ruview-live@ruview`, with
     source `./harness/ruview/mod`.
   - One copy serves both installs: the npm package and the marketplace.
2. **Behaviour.**
   - **`/ruview`** toggles a pane (`ruview-live`). While it is open, a
     `$.clock.every` timer (default 15 s, minimum 5 s) runs one read-only
     capture.
   - **`/ruview refresh`** runs one capture and returns the summary.
   - **`/ruview off`** closes the pane.
   - **The pane** shows nodes (rate, loss, RSSI, shape, SYNTHETIC flag), the
     optional ESPHome radar (presence, distance, device-reported vitals), and
     alerts, including heartbeat-only boards with the CSI-buffer-starvation
     hint. It has Refresh (`r`) and Close (`c`) buttons.
   - **The status line** is set on every refresh.
3. **Data comes only from the harness CLI beside the mod.**
   - The mod runs `node <plugin root>/../bin/cli.js esp32 … --json` and
     `mmwave --source esphome … --json`, as fixed argv arrays, through
     `$.process.run`. So the pane shows what the tested tools return.
   - Mods may import nothing but their own files and `claude-code` (the
     validator refuses `node:url`). The CLI is therefore located through
     `$.plugin.root`.
4. **Least authority.**
   - The mod never runs a write verb (flash, calibrate, train). A unit test
     pins the argv.
   - The radar host is validated before use.
   - Options are bounded: ports 1024–65535, refresh ≥ 5 s, capture 1–10 s.
5. **Discovery.** `ruview mod` (and `ruview mod --json`) prints the installed
   path, the `claude --plugin-dir` command, the marketplace commands, usage,
   settings, and the early-access note.

## Evidence

All on Claude Code 2.1.286, Windows 11 x64.
- **Validation:** `claude plugin validate harness/ruview/mod` passes. It lists
  hooks `session.start`, `command.run{ruview}`, `ui.render{Pane}`,
  `ui.close{ruview-live}` and `session.end`, and calls `$.clock.every`,
  `$.clock.now`, `$.command.register`, `$.process.run` and `$.ui.*`.
  `claude plugin validate .` passes for the marketplace.
- **Engine tests:** `claude plugin test harness/ruview/mod`, with
  `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`, passed 2/2 in three consecutive
  runs. They check:
  - `/ruview` opens the pane and runs the exact read-only argv;
  - the status reads `RuView · 2 nodes · 1 alert`;
  - the timer refreshes while open and **never after close**;
  - an honest `no_packets` status.
- **Harness unit tests:** `test/mod.test.mjs`, 6/6, under plain Node:
  settings bounds, host validation, argv, failure parsing, model/status, pane
  drawing and button wiring, and the no-imports rule.
- **Real engine, headless (MEASURED):**
  `claude --plugin-dir ./mod -p "/ruview refresh"` answered
  `RuView · 0 nodes · 1 alert` (no CSI node was streaming). With `radarHost`
  set to the live Seeed MR60BHA2 kit, it answered
  `RuView · 0 nodes · radar clear · 1 alert`.
- **Note:** under Git Bash a leading `/ruview` is rewritten into a Windows path
  unless `MSYS_NO_PATHCONV=1` is set. This is not an issue inside the Claude
  Code prompt.

## Consequences

- An operator sees node and radar health beside the conversation without
  asking for it. Agents see the same facts through MCP.
- **Mods are early access.** The API may change between Claude Code releases,
  and hooks modules load only where function hooks are enabled. The mod is
  therefore optional, and nothing else in the package depends on it.
- **Trust.** Like every mod, it runs inside Claude Code with Claude Code's
  access. It is read-only by construction, and the README says to install it
  only from a trusted source.
- A refresh binds UDP 5005 for the capture window. While the sensing server
  holds the port, the pane reports `port_in_use` instead of reading.