Repository navigation
Description
Held RFC. This is a design proposal for discussion. It carries hold so no hive agent picks it up until maintainers settle Decisions for maintainers. It is one of three related Activity Monitor RFCs: #15860 (wall display mode), #15861 (hub-wide monitor) and this one (Matrix code-rain mode). It stands alone, and it gets better with #15860's display shell.
| Field | Value |
|---|---|
| Status | Proposal, not accepted |
| Target | v5 for Phases 1β2 (spoke and dashboard). Phase 3 (hub) follows #15861. The hivectl view belongs on v6 |
| Scope | src/pkg/dashboard (new line source, SSE frame and backlog endpoint), a tap on the sentinel's existing PR-patch fetch (listPRFilesWithPatch, src/pkg/github/sentinel_sweep.go:574), src/crux/logscrub (ScrubString, RedactPaneTokens), new static-src/js/matrix.js and css/matrix.css |
| Out of scope | Agent reasoning or pane text, terminal output, diffs of files hive did not change, any new GitHub API polling |
| Related | #15860, #15861, #13379 (sentinel per-event evaluation), src/docs/streaming-the-activity-monitor.md |
Summary
The Activity Monitor shows where work is. Matrix mode shows what is being written. It is an ambient screen: the actual lines of code hive's agents add, streamed as they are pushed, rendered as falling code rain or one of a few other effects. It is something to leave on a spare monitor or a lobby TV so people get a feel for the pace and texture of the work. Glance at it and you see Go in one column, YAML in another, and a burst of test code when a fixer lands.
Two rules shape the design: only code hive is already pushing, and never anything that looks like a secret.
Where the lines come from
The proposed source needs no new GitHub calls.
- Phase 1, pushed lines. A
pull_requestopened,synchronizeorreopenedwebhook already hands the PR to the sentinel (forgestate: sentinel and projects v2 move to event-driven + reconcile cadenceΒ #13379), and the sentinel fetches its files with patches (listPRFilesWithPatch). Matrix taps that result:- For each file, it parses the unified diff, keeps the
+lines, and drops every line it has already shown for that PR. A per-PR set of line hashes, kept for 24 h, means a force-push or rebase shows only genuinely new lines. - When the sentinel is disabled, the line source makes the same single files call itself, once per head.
- For each file, it parses the unified diff, keeps the
- Phase 4, pre-push lines (Decision 1). Lines straight from agent working trees as agents type, before any push. This is more live, but it needs read access into the agent sandbox and a design for where each agent's tree lives on each runtime (tmux, job sandbox, contributor relay). The RFC parks it until Phase 1 shows the effect is worth it.
Whose code. The default is PRs whose tracker author_kind is hive or clanker. Human contributors' PRs, and PRs from untrusted forks, are excluded unless dashboard.matrix.authors: all is set. A wall screen should not render arbitrary text that strangers submit.
Safety pipeline (server side, before anything leaves the spoke)
- Path deny-list. Skip:
.env*,*.pem,*.key,*.p12,id_*;- paths containing
secret,credentialortoken; - lockfiles and
go.sum; vendored, generated, minified or binary files; - anything matched by
dashboard.matrix.exclude_paths.
- Line scrub. Run
logscrub.ScrubStringandRedactPaneTokenson every line. Any line that changes is dropped, not shown redacted. A wall should never show***REDACTED***next to a variable name. - Entropy guard. Drop any line with a run of 32 or more base64 or hex characters, since that catches keys the regexes miss.
- Shape limits. Lines are capped at 160 characters, trimmed, with empty lines skipped. At most 200 lines per PR head, so a 5,000-line vendored import cannot flood the screen.
- Private repositories are off by default (
dashboard.matrix.private_repos: false). - Who may watch. Any role that can read the tracker. A π RFC: Activity Monitor kiosk/display mode for wall-screen dashboardsΒ #15860 display credential sees Matrix only if it was minted with
matrix: true.
Transport
-
SSE frame
code-lineson/api/events. Lines are batched to at most one frame per second and at most 200 lines per frame:{"repo":"o/r","pr":1234,"head":"abc123","author_kind":"hive","path":"pkg/x/y.go","lang":"go", "lines":["if err := ctx.Err(); err != nil {","\treturn nil, err","}"],"at":"2026-10-30T18:47:00Z"} -
GET /api/matrix/backlogreturns the last 2,000 accepted lines from an in-memory ring, so a screen that starts up or reconnects begins full rather than empty. Nothing is persisted to disk. -
langcomes from the file extension. Syntax colouring happens in the browser.
Effects
Each effect is a small, self-contained renderer on one <canvas>, using a glyph atlas, requestAnimationFrame, and pausing while the tab is hidden.
| Effect | What it looks like |
|---|---|
| Rain (default) | Classic digital rain, except the glyphs in each column are characters from real incoming lines, read top to bottom. The head glyph is bright, the trail fades, and a few glyphs mutate. A new line enters as a new column. |
| Cascade | Whole lines fall at varying speeds, readable when you stop and look, with a repo#PR path caption on hover. |
| Ghost coder | A fake editor types lines into a file tab named after the real path, with syntax colour and a blinking cursor. Each PR gets its own tab. |
| Terminal | A green + diff scroll, like a git log -p that never ends. |
| Constellation (hub, #15861) | Each hive gets a band of colour, and line density shows who is busy. |
Settings live in the β panel and the #15860 overlay. They are stored in localStorage under hive.matrix.*, and every one is also a URL parameter (mx.*) so a display link can carry it:
- effect, speed, density, font size, maximum FPS (30 by default, for TVs and Raspberry Pi-class devices);
- palette: classic green, amber, hive gold, per-hive colours, or syntax colours;
- glyph mutation rate and trail length;
- caption on or off (
repo#PR Β· path); - filters by repo, language and hive;
- idle behaviour when nothing new arrives for N minutes: replay the backlog dimmed, plain rain, or a stats card ("1,284 lines today across 37 PRs");
- quiet hours (dim between set times);
- sound, off by default: a soft tick per line batch, reusing the tracker's volume control.
prefers-reduced-motion switches to a static, slowly paging view of the latest lines.
Entry points:
- a Matrix tab in the Activity Monitor header;
?kiosk=1&view=matrix;matrixas a π RFC: Activity Monitor kiosk/display mode for wall-screen dashboardsΒ #15860 playlist view;hivectl tuigains a Matrix pane on v6 (terminal rain over the same SSE frame).
Phases
- Spoke source. The sentinel tap, the safety pipeline, the
code-linesframe, and the backlog endpoint, behinddashboard.matrix.enabled(default false). - Dashboard. Rain plus one readable effect (Cascade), the settings, and display mode. The other effects follow, one PR each.
- Hub. The browser connects to each visible hive's Matrix stream through the hub's existing hive routes, so the fan-in happens client side and the hub does not relay. This adds the Constellation effect. Hive scoping follows π RFC: Hub-wide Activity Monitor with per-hive aggregationΒ #15861 Β§C.
- Pre-push source (Decision 1).
Security
- Every line has already been pushed to a branch on the forge. Nothing new leaves the hive's trust boundary for public repos.
- Lines that match secrets are dropped, never masked. Private repos and non-hive authors are opt-in.
- Text renders to a canvas or as text nodes, never as HTML.
docs/streaming-the-activity-monitor.mdgains a section on Matrix mode and private code.
Cost
- GitHub: zero extra calls with the sentinel on. Otherwise one files call per new PR head.
- Spoke: diff parsing per push, a 2,000-line ring (~300 KB), and per-PR hash sets for 24 h.
- Browser: one canvas. The target is at most 15% of one core at 1080p/30 fps on Raspberry Pi 4-class hardware. Phase 2 measures this.
Acceptance
- A hive-authored push to a public repo shows its added lines on an open Matrix view within 5 s of webhook receipt.
- A fixture diff containing a GitHub token, an AWS key, a PEM block and a
.envfile renders none of them. Covered by a Go test over the pipeline. - Force-pushing the same content again shows no duplicate lines.
- A PR by a human contributor, or in a private repo, shows nothing under the defaults.
- A fresh display shows backlog lines immediately. Hiding the tab stops the animation loop.
changelog.dfragment per phase.
Alternatives
- Commit messages and file names only. Safer, but it isn't what anyone wants to watch. It survives as the caption.
- Agent pane text. It shows reasoning, but it is noisy (builds, tool chatter) and much harder to scrub. Pane output already has its own viewer gate (
paneTailViewer) for good reason. - A third-party "code rain" screensaver against the GitHub API. It needs a token on the display, has no hive scoping and no scrub, and burns rate limit.
Decisions for maintainers
- Pre-push lines. Pursue live lines from agent working trees (Phase 4), or stay with pushed lines only?
- Author default. Hive and clanker only (proposed), or all authors on public repos?
- Drop vs mask. Drop any line logscrub touches (proposed), or show a masked line?
- Sentinel coupling. Tap the sentinel's patch fetch (proposed), or give Matrix its own fetch so the two features stay independent?
- Which effects ship first. Rain + Cascade (proposed), or Rain + Ghost coder?
Activity
[-]π RFC: Matrix mode β streaming live code changes as visual effects[/-][+]π RFC: Activity Monitor Matrix mode β ambient code rain of the lines hive is pushing[/+]hivecommons-hive commentedon Oct 31, 2026
Parking on
stage/045-needs-decision: this RFC is marked Proposal, not accepted and its body says it should carryholduntil the Decisions for maintainers are settled, but the label was never applied, so it landed in the actionable queue. The hive will not implement an unaccepted design that streams source lines from PR patches onto public wall screens.Risk: public-facing behaviour / secret exposure (rendering code lines from pushed patches on ambient displays).
Maintainer question β pick one and the hive proceeds:
logscrubtouches, tap the sentinel's patch fetch, ship Rain + Cascade first.Reply
/hive decision A|B|C(or/hive approvefor A). Related: #15860, #15861.β hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88
hivecommons-hive commentedon Oct 31, 2026
What to reply
/hive approve: go with the recommendation/hive decision <your instructions>: go ahead, following your instructions/hive help: show these againIf what this issue waited on has been done (a merged fix, or an action taken outside this repository), a maintainer can reply
/fixedto close it as completed; Hive clears its park labels.Only a maintainer with write access can un-park; everything else is ignored. Full command reference: https://github.com/hivecommons/hive/blob/v5/src/docs/maintainer-commands.md.
clubanderson commentedon Oct 31, 2026
/hive decision Proceed as an explicitly opt-in experimental display feature, default OFF, without altering the normal tracker. Pushed lines only: do not inspect or stream agent working trees, pre-push content, reasoning, panes or terminal output. Restrict authors to the existing positively identified Hive/clanker identities; no expansion to arbitrary public-repo authors. Drop any line touched by secret scrubbing rather than showing a masked fragment; honor content exclusions and omit sensitive/denied paths before fetching or publishing content. Reuse the existing authorized sentinel patch fetch through a bounded optional observer: no separate GitHub polling, no blocking or destabilizing sentinel, and no additional content retention when disabled. Limit buffers, backlog, line sizes and delivery rate. Ship Rain plus Cascade first, with reduced-motion/static fallback, pause and clear source/freshness labels. Enforce repository/user authorization on every content endpoint and stream; display/kiosk/public-route availability never grants code access. Hub content delivery is deferred until the hub authorization design is proven. Preserve current tracker and pipeline stages. No live enablement or deployment is authorized.
clubanderson commentedon Oct 31, 2026
/hive decision Additional owner requirement: Matrix display needs its own dedicated Twitch channel and independently configured broadcast. Existing twitch.tv/hivecommons remains the full-screen Activity Monitor and must not be changed or interrupted. Channel name/account provisioning is pending owner confirmation. Reuse existing streamer infrastructure with separate source URL, credentials reference, process/deployment identity and failure isolation. Twitch is PUBLIC: a dashboard-authenticated code stream is not automatically broadcast-safe. Explicit public repository/content allowlisting, existing author restrictions and scrub/drop rules are required; never expose private repository patches or excluded content. Keep display/broadcast opt-in and OFF until owner authorization and channel provisioning. No stream keys in issues or source.
clubanderson commentedon Oct 31, 2026
/hive decision Owner confirmed the proposed dedicated Twitch channel name: hivecommonsmatrix (https://twitch.tv/hivecommonsmatrix). Use this as the intended Matrix broadcast destination. This confirms naming only; channel availability/account provisioning and secure stream-key installation remain unverified. Keep existing twitch.tv/hivecommons unchanged. Prior explicit public-content allowlisting, scrub/drop rules, independent broadcast and disabled-until-provisioned requirements remain in force.
39 remaining items
hivecommons-hive commentedon Oct 31, 2026
PR #16046 covers this issue: #16046
The PR body says this is partial/non-closing work (
Refs/Part ofor leave-open wording), so Hive will not add a closing keyword. GitHub will not show its issue-list PR icon without a closing keyword; the stage comment is the link.hivecommons-hive commentedon Oct 31, 2026
All children delivered: #15928 β PR #15945, #15933 β PR #15946, #15934 β PR #15967, #15935 β PR #15977, #15936 β PR #16020, #15937 β PR #15985, #16041 β PR #16046, #16042 β PR #16043.
Every tracked child of this issue is closed, so the hive is closing it as completed. Reopen it if something it asked for is still missing.
github-actions commentedon Oct 31, 2026
@hanthor this issue was closed by @hivecommons-hive[bot] as completed.
If this was closed by a merged PR, the fix only takes effect once it ships in a tagged release and your deployment updates to it β check your running version against the fix before concluding the fix failed.
If you are still seeing the problem, comment
/reopenand it will be reopened for you β you do not need write access. Please add what you are still observing (running version, logs, steps) so it is not closed the same way again.β¨ feat(notifications): attention-pilot opt-in flag and issue-side hivβ¦