hivemind-custom-view
Skill17 starsChanged 12 days agoMITView on GitHub
Build a custom Hivemind workspace view — a sandboxed plugin that redraws the whole canvas from the host's projection of frames, tiles and agent status. Covers the v1 protocol, the surface hole-punch for live terminals, the render-on-demand rule, theming, permissions, packaging and install. Use when writing a new view, debugging one that renders nothing, or reviewing a view PR.
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- guide/AGENTS.mdAGENTS.md
- spec/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- adding-an-agent-providerSkill
- ascii-character-animationSkill
- feature-doneSkill
- hive-browserSkill
- hivemind-live-wallpaperSkill
- maintaining-docsSkill
- test-auditSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 3 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 22
Read reference.md for the full message vocabulary and checklist.md for what "done" means.
- Very specific: line 88
Call invalidate() on a real change.
- Very specific: line 90
If you genuinely animate (an easing, a spring settling), drive it from invalidate() while the animation is live and stop calling it when …
- Distinctive: line 129
Do not draw your own chrome there.
- Very specific: line 148
Check supports first: an older host counts the message against your view.
- Very specific: line 155
Never ask for the text by another road.
- Very specific: line 178
Check supports first: the app serves your view its own SDK, and an app before 1.18 has no onWidgetBand.
- Very specific: line 193
Write background: var(--hm-color-bg2) and your view follows the user's theme for free.
- Distinctive: line 221
All additive, and none needs a permission.
- Very specific: line 247
Every on… and activity returns its unsubscribe.
- Very specific: line 303
When someone asks to see a tile while your view is on screen (a widget's "go to" button, a notification's View, a toast's Show, hive ctl …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Building a Hivemind view
Why this exists
A view is not a panel in the app. It is the app's window onto running work: when a view is active it draws every frame, every tile and every agent's status, and the user is looking at your canvas instead of Hivemind's. A view that stops drawing does not degrade — the user loses sight of agents that are still running.
The trap is not the protocol, which is small. It is that a view runs under
default-src 'none' in an opaque origin, and the web reflexes that fail there fail
silently. fetch() of anything but the view's own files does not throw a useful error, it
is refused by connect-src. A Google Font link loads nothing. An <iframe> is frame-src
'none'. A CDN <script> is not on hm-view:. Authors lose an afternoon to a blank
canvas because they assumed a normal page.
Read reference.md for the full message vocabulary and checklist.md for what "done" means.
What you are given, and what you may do
The host sends a projection, not the workspace. You get frames (id, title, colour), tiles (id, frameId, kind, name), selection, per-tile status on subscription, theme, viewport and visibility. A 1.3 host also gives you when each status began, discrete events, output levels, whether the user is at the machine, and a day's history. You never get a command line, a working directory, file contents, or anything a terminal is showing — output is a level from 0 to 3, never text or a byte count.
You may send back: selection and focus changes, surface rects, a reveal answer, a persisted layout blob, a frame count, and — only if the manifest asked — spawn and close commands.
That asymmetry is the design. A view decides how the workspace looks; it does not decide what runs.
The smallest view that works
hive plugins new view my-view writes all of it — the manifest, an entry page, src/main.ts, the
build, and the SDK's source under types/view-sdk/ for tsc. The id is scoped to the GitHub
login (@login/my-view); HiveHub refuses any other scope. The parts:
{
"id": "@login/my-view",
"name": "My view",
"version": "0.1.0",
"entry": "index.html",
"protocol": 1,
"permissions": []
}import { applyThemeVars, connect, createInvalidator } from "@hivemind/view-sdk";
const hm = await connect(); // resolves after the host's hello
applyThemeVars(hm); // --hm-color-*, --hm-accent, --hm-font-*, …
let frames = [], tiles = [];
const { invalidate } = createInvalidator(hm, draw);
hm.on("structure", (s) => { frames = s.frames; tiles = s.tiles; invalidate(); });
hm.on("names", ({ names }) => { /* titles changed, nothing structural */ invalidate(); });
hm.on("resize", () => invalidate());
function draw() { /* paint frames and tiles into your canvas or DOM */ }connect() rejects after 10 s if no handshake arrives. Await it before touching
anything else — hm.hello is not populated until it resolves.
The rule that matters most: draw on demand
Never run a requestAnimationFrame loop. The host checks whether a view is
drawing, and a view that paints 60 times a second while nothing changes burns the
user's battery behind a workspace they are not even looking at.
createInvalidator(client, draw) is the whole discipline: it coalesces to one frame,
skips drawing entirely while hidden, remembers that it was dirty, and draws one
catch-up frame when the view becomes visible again. It also calls reportFrame() for
you, which is what the host reads.
Call invalidate() on a real change. That is it.
If you genuinely animate (an easing, a spring settling), drive it from invalidate()
while the animation is live and stop calling it when the animation ends. An animation
that never ends is a rAF loop wearing a costume.
A 3D view: nothing comes close enough to fill the screen
The camera comes close (a workspace of one project, a walk through someone's eyes), and whatever flies or floats between it and the ground comes closer still. Give each such thing the most it may show on screen: a pin keeps one size, a bird nearer than 90 px is drawn smaller, a cloud fades out near the camera. Work that out from the thing's farthest reach (animation at its widest), from its nearest point, stretched as the lens stretches what is off to the side. Test it by projecting its real shape at the closest distances the camera allows, against a number the test states itself.
Two three.js traps that drew Archipelago's birds as black shards:
- A transparent
DoubleSidematerial is drawn in two passes, and in both every face drawn reads as front facing:gl_FrontFacingcannot tell a back from a belly. Decide by where the camera is, or keep the material opaque. A transparent one that does not write depth is also painted over by every transparent layer drawn after it. camera.lookAtleavesmatrixWorldInversewith last frame's rotation until the renderer draws. Callcamera.updateMatrixWorld()where the camera moves when anything that frame projects through it.
Surfaces: the hole punch
A live terminal is a real xterm the host owns. A view cannot render one. What you do is declare where one belongs and the host positions it above your iframe:
hm.setSurfaceRects([{ tileId, x: 320, y: 0, w: hm.viewport.w - 320, h: hm.viewport.h }]);Coordinates are pixels in your viewport. At most 16 rects. Identical rects are not re-sent, so calling it on every draw is cheap and correct.
Three things authors get wrong:
- The rect is a hole, not a layer. Anything you paint under it is invisible. Do not draw your own chrome there.
chrome: "none"means you own undocking. The default"bar"gives the host's slot bar (name, status, pop-out, undock) and is what you want unless you have built that affordance yourself.- Listen for
undock. The user can undock from the host's bar or with Shift+Esc. The tile is already released when the message arrives; drop the rect from your model or your UI will claim a surface that is gone.
Line slots: the host draws what a tile last said
A view never gets the text a terminal showed or an agent wrote. To show a tile's last line (what
its screen last showed, what its agent last said, or, while it waits on the person, what for), leave
room for it and let the host draw it (protocol 1.17, feature lineSlots):
if (hm.supports("lineSlots")) hm.setLineRects([{ tileId, x: 16, y: 40, w: 480, h: 24 }]);- At most 64 rects, each at least 20px high. Identical rects are not re-sent.
- Check
supportsfirst: an older host counts the message against your view. A phone and a remote screen do not draw lines, and do not say the feature. - The host draws the line in 11px mono, and for a permission it can answer, its own Review button inside your rect: a popover of the host's that names the tile and shows all of what the agent would run, with Deny where the keyboard lands. Never Allow in your rect, however short the command: you place the rect, so you could place the button under the person's pointer. The pointer passes through the line to you; the button takes it.
- Never ask for the text by another road. The rule is the one for
invokeResultand your saved layout: what you hold, you can pass on.
Widget band: keep clear of the cards the app floats over you
The app floats the workspace's widget cards over your view, stacked down its widget edge (the
right, or the left with "widgets": "left" in the manifest). Your header, labels and the part of
your scene you frame things in belong outside them (protocol 1.18, feature widgetBand):
let band = { edge: "left", width: 0 }; // a phone floats no cards: no band
if (hm.supports("widgetBand")) hm.onWidgetBand((b) => { band = b; layout(); });
// An app before 1.18 floats cards and does not say the band: one column while a card floats.
else if (hm.supports("widgets") && !hm.device.compact) hm.onWidgets((ws) => {
band = { edge: "left", width: ws.some((w) => w.card && w.placement === "screen") ? 268 : 0 };
layout();
});widthis CSS px from your widget edge to the far side of the cards, the gap beside them included; 0 when there are none (none added, all hidden, a person moved them all).- It comes right after
hello, then whenever cards come or go, start a second column, or the window is resized. A late listener hears the current one at once. - Check
supportsfirst: the app serves your view its own SDK, and an app before 1.18 has noonWidgetBand. Every app window says the band, a guest's over the host's view too. A phone floats no cards over a view and does not say the feature: the band there is none, take 0.
Theme: never hardcode a colour
applyThemeVars(hm) writes the host theme onto your document as custom properties and
keeps them current when the user changes appearance:
--hm-color-<token> every colors entry (bg, bg2, fg, brand, ok, …)
--hm-accent --hm-radius --hm-font-ui --hm-font-mono
--hm-surface --hm-terminal-bg --hm-glass (0|1) --hm-modeWrite background: var(--hm-color-bg2) and your view follows the user's theme for
free. A hardcoded #1a1a1a is a view that is unreadable the moment someone switches to
light mode.
The four status colours are meaning, not decoration. idle, working, blocked and exited read as those states everywhere else in the product. Do not spend them on anything else — a view that colours decorative particles amber teaches the user to ignore "working".
Status is a subscription
Status does not arrive with structure. Subscribe per tile, and keep the
unsubscribers:
const off = new Map<string, () => void>();
hm.on("structure", ({ tiles }) => {
for (const t of tiles) {
if (!off.has(t.id)) off.set(t.id, hm.subscribeStatus(t.id, (s) => { status.set(t.id, s); invalidate(); }));
}
for (const [id, stop] of off) if (!tiles.some((t) => t.id === id)) { stop(); off.delete(id); }
});Leaking subscriptions for closed tiles is the most common resource bug in a view.
Protocol 1.3: time, events, activity, presence, history, share
All additive, and none needs a permission. Detect them from the field, never by probing a method: the app serves its own SDK to your view, so on an older app the 1.3 methods do not exist at all.
const has = new Set(hm.hello.features ?? []); // "since" | "events" | "activity" | "presence" | "history" | "share"| You want | Write | Notes |
| How long a tile has been waiting | hm.subscribeStatus(id, (s, info) => …) | info.since is when the status began; info.exact === false means the host found it already there — show "≥" |
| Turn finished, needs you, subagents, tile opened/closed | hm.onEvents(["turn", "needsInput"], cb, { replaySince }) | one batched message per task; replaySince gets up to 100 buffered events from the last hour |
| Events your scripts send | hm.onCustom("ci.*", cb) | from hive ctl view emit ci.build '{"state":"failed"}'; data is untrusted — render it as text |
| How busy a tile is | hm.activity(id, (level) => …) | 0–3, at most 4 messages a second, none while hidden |
| Whether the user is there | hm.onPresence((p) => …) | active / idle (2 min) / away (10 min or locked) |
| A day you were not mounted for | await hm.history("2026-09-23") | per-tile status intervals, turns, gaps the host did not watch, presence as day totals |
| Let the user keep an image | await hm.share(pngArrayBuffer, { suggestedName }) | the host shows it and asks; you get copied, saved or cancelled, never a path |
Two rules keep these honest:
- An activity message is your animation clock. Step a typing robot once per message; do
not start a
requestAnimationFrameloop because something is busy. When everything is quiet, no messages arrive and nothing should draw. - History is what the host watched. A
gapis time nobody was looking — the app was closed, or a machine was offline. Never count it as idle or as waiting.
Every on… and activity returns its unsubscribe; drop a closed tile's activity the way you
drop its status subscription.
Protocol 1.4: the agents
| You want | Write | Needs |
| Why an agent waits, how its turn ended, its subagents | hm.subscribeStatus(id, (s, info) => info.agent) | feature agentStatus; turn events carry outcome |
| Which agents are installed and what they can do | await hm.agents() | feature agents |
| A folder's past sessions, to continue one | await hm.sessions(agent, frameId), then spawnAgent(agent, frameId, { resume: id }) | workspace:sessions |
| Give an agent an instruction | await hm.prompt(tileId, text) → sent / cancelled | workspace:prompt; the user reads and sends every one |
A prompt is the one way a view makes an agent act, so the host shows the full text and focuses Cancel; three cancels decline the view's prompts until it reloads. Never retry a cancel. A view never gets an agent's replies, answers its permission prompts, or sees a title the agent wrote.
Protocol 1.5: people, the device, and a host for your tests
| You want | Write | Notes |
| Who else is in a shared workspace | hm.onParticipants((people) => …) | feature participants; { id, person, name, color, cursor: { tileId } | null, selection }, never the person at your view |
| Lay out for a phone or a finger | hm.device → { touch, compact } | always there: a desktop's from an older host |
| Test without the app | fakeHost() from @hivemind/view-sdk/testing | host.send(...), then host.commands, host.rects, host.refused (the app's reasons) |
cursor is the tile someone's pointer is over and selection what they selected, only ever of
your tiles and frames: ring them in the person's color, never in a status colour. A surface
rect waits for a structure naming its tile, so a docked tile restored from your layout that no
longer exists is never sent — the host would count it as a refusal.
Permissions: ask for nothing
The base set — projection, status, selection, reveal, surfaces, layout — needs no permission. Only five exist:
| Permission | Unlocks |
workspace:spawn | spawnTile, spawnVis, spawnClaude, addFrame, spawnAgent |
workspace:close | closeTile |
workspace:edit | renameTile, openFolder |
workspace:prompt | prompt, and spawnAgent with a prompt (1.4) |
workspace:sessions | sessions, and spawnAgent with resume (1.4) |
Requesting one is a line in the install review a user has to accept, and an unknown
name is refused at install and at load. Calling a command your manifest did not
request throws locally, so a missing permission shows up as a broken button, not a
silent no-op. Ship with "permissions": [] unless a feature genuinely needs more.
Persisting your own state
hm.setLayout(data) stores an opaque blob (≤ 64 KB) under your plugin id, debounced.
It comes back as hm.hello.layout on the next mount. Use it for view-owned state — a
zoom level, a spread, which panel is open. Do not put workspace state there; the
workspace already has some.
Answer reveal: show the tile
When someone asks to see a tile while your view is on screen (a widget's "go to"
button, a notification's View, a toast's Show, hive ctl focus <tile>), the
app does not move a canvas that is not there: it selects the tile and sends your view
reveal. Bring the tile into view (move your camera to it, open it, dock its terminal
if that is how your view shows one), then answer where it is drawn, in your
coordinates, or null for a tile you do not draw:
hm.onReveal((tileId) => {
if (!drawn(tileId)) return null;
flyTo(tileId);
return rectFor(tileId);
});Answering with a rect and moving nothing is the mistake to avoid: every "go to" in the
app then does nothing while your view is open, which reads as a broken app. reveal
names tiles only; a frame is never revealed.
Build and install
One directory with the entry, the manifest, and everything bundled — except the SDK. The app
serves @hivemind/view-sdk on every view origin and maps the bare import to it, so it stays
external; a bundled copy would pin an SDK older than the app it runs in. Any other bare import
at runtime fails.
await build({ entryPoints: ["src/main.ts"], bundle: true, format: "esm", target: "es2022",
outfile: "dist/main.js", external: ["@hivemind/view-sdk"] });
cpSync("index.html", "dist/index.html");
cpSync("hivemind-view.json", "dist/hivemind-view.json");npm run dev # build, then hive plugins install dist; ⌘E in the app until your viewAn entry ending in .js is wrapped in a host-generated page for you — use that when
you have no HTML of your own. Everything referenced must be a relative path inside the
package; a symlink pointing out of it is refused, not followed.
What the sandbox refuses
Your CSP is default-src 'none' with scripts and styles only from hm-view:.
Concretely:
| You wrote | What happens |
fetch("./data.json"), XHR of your own files | declare "files": true in hivemind-view.json and check hm.supports("ownFiles"). Works from Hivemind 2026.10.6, in the app and a browser tab: connect-src names your own origin (hm-view://<host>, or your path in a tab) and nothing else. Refused on the phone page and without the declaration; bundle what the phone shows |
<img>, <link rel=stylesheet>, import() of another view's files | refused: every source list names your own origin only |
fetch() of anything else / WebSocket | refused, another view's files too. There is no network, by design |
<link> to Google Fonts, a CDN script | loads nothing, no error worth reading |
<iframe> | frame-src 'none' |
require, process, node:* | there is no node here |
localStorage | opaque origin — use setLayout |
<form> | its submit event fires, in the app and on the phone page, and form-action 'none' keeps it from going anywhere: handle the event and call preventDefault() |
Notification, getUserMedia, geolocation | refused — a view gets no browser permission |
Images, fonts and media may be data:, blob: or bundled files. Workers may be
blob:. WebAssembly is allowed (wasm-unsafe-eval). Bundle what you need.
Start from a person, not a visual
A view that looks impressive and helps nobody is the easiest kind to build and the most common
kind to delete. Before any pixels, write down who it is for and the one job it makes easier —
"never leave an agent waiting", "type into every terminal of this task at once" — and cut
anything that does not serve that job. docs/design/views-by-persona-2026-09-16.md is the worked
example.
True, and not guessable
Each of these cost a view real time to find out.
- Only the active view is mounted. Switching to Canvas unmounts yours. On a 1.3 host,
since,replaySinceandhistory()tell you what happened meanwhile. On an older one you cannot record history while you are not on screen — persist timestamps insetLayout, and show a remembered one only as "since", only if the tile is still in that state. - The app's settings button floats over the top-right ~56px of every view. Keep your own controls, and the host bar of any surface rect, out of that corner.
- The status colours are the app's: working =
brand, needs you =warn, idle =fg3, exited =err. Remap them and the user misreads the rest of the app. Frame colours identify a frame; mute them so they never compete with a status. - Every agent tile has kind
claude, whatever the provider. AplanReviewtile is a human decision waiting, which usually belongs with "needs you". - On arrival,
selectioncarries whatever was last selected on the canvas (fresh: false). Mark it; do not dock it — the user came to your view, not to that tile. - Keys reach your view only while its document has focus, and a docked terminal takes them.
Give the view a focusable element (
tabindex="0") and say which keys it answers. chrome: "bar"puts the host bar above the tile's own header — two headers. Use"none"when your view already shows the tile's name and a way to close it.
Check it against real states
cd apps/desktop
xvfb-run -a -s "-screen 0 3400x2200x24" node scripts/view-check.mjs <view folder or @owner/name> <out-dir> [palette]It runs the built app on a private profile, spawns agents through a claude shim whose screens
are the ones the real detector reads — working, asking permission, idle — and screenshots your
view in each state. Two things it learned the hard way: the app types an agent's first prompt
once its screen reads idle (it is not an argument), and a "working" screen that stops moving
reads as finished, correctly, because a real one never stops.
Before you finish
| Mistake | Fix |
| Blank canvas, no error | You drew before await connect(), or you assumed network |
| Fan spins on an idle workspace | A rAF loop. Use createInvalidator |
| Unreadable in light mode | Hardcoded colours. Use --hm-color-* |
| Terminal appears in the wrong place | Rects are viewport pixels, and stale after resize |
| A closed tile still has a surface | You ignored undock, or leaked its status subscription |
A widget's "go to", a notification's View or hive ctl focus does nothing in your view | No onReveal, or it answers without moving to the tile |
| Something near the camera covers the view | Nothing caps its size on screen: see "A 3D view" |
| Button silently dead | Command needs a permission the manifest did not request |
Work checklist.md before calling a view done; it is the definition of done for a view PR and belongs in the description.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

