agentleFS
dip497dip497/hivemind/.claude/skills/hivemind-custom-view/SKILL.md

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.

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
  1. Distinctive:

    Read reference.md for the full message vocabulary and checklist.md for what "done" means.

    line 22
  2. Very specific:

    Call invalidate() on a real change.

    line 88
  3. Very specific:

    If you genuinely animate (an easing, a spring settling), drive it from invalidate() while the animation is live and stop calling it when …

    line 90
  4. Distinctive:

    Do not draw your own chrome there.

    line 129
  5. Very specific:

    Check supports first: an older host counts the message against your view.

    line 148
  6. Very specific:

    Never ask for the text by another road.

    line 155
  7. Very specific:

    Check supports first: the app serves your view its own SDK, and an app before 1.18 has no onWidgetBand.

    line 178
  8. Very specific:

    Write background: var(--hm-color-bg2) and your view follows the user's theme for free.

    line 193
  9. Distinctive:

    All additive, and none needs a permission.

    line 221
  10. Very specific:

    Every on… and activity returns its unsubscribe.

    line 247
  11. Very specific:

    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 …

    line 303

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 DoubleSide material is drawn in two passes, and in both every face drawn reads as front facing: gl_FrontFacing cannot 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.lookAt leaves matrixWorldInverse with last frame's rotation until the renderer draws. Call camera.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 supports first: 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 invokeResult and 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();
});
  • width is 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 supports first: the app serves your view its own SDK, and an app before 1.18 has no onWidgetBand. 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-mode

Write 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 wantWriteNotes
How long a tile has been waitinghm.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/closedhm.onEvents(["turn", "needsInput"], cb, { replaySince })one batched message per task; replaySince gets up to 100 buffered events from the last hour
Events your scripts sendhm.onCustom("ci.*", cb)from hive ctl view emit ci.build '{"state":"failed"}'; data is untrusted — render it as text
How busy a tile ishm.activity(id, (level) => …)0–3, at most 4 messages a second, none while hidden
Whether the user is therehm.onPresence((p) => …)active / idle (2 min) / away (10 min or locked)
A day you were not mounted forawait 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 imageawait 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 requestAnimationFrame loop because something is busy. When everything is quiet, no messages arrive and nothing should draw.
  • History is what the host watched. A gap is 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 wantWriteNeeds
Why an agent waits, how its turn ended, its subagentshm.subscribeStatus(id, (s, info) => info.agent)feature agentStatus; turn events carry outcome
Which agents are installed and what they can doawait hm.agents()feature agents
A folder's past sessions, to continue oneawait hm.sessions(agent, frameId), then spawnAgent(agent, frameId, { resume: id })workspace:sessions
Give an agent an instructionawait hm.prompt(tileId, text) → sent / cancelledworkspace: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 wantWriteNotes
Who else is in a shared workspacehm.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 fingerhm.device → { touch, compact }always there: a desktop's from an older host
Test without the appfakeHost() from @hivemind/view-sdk/testinghost.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:

PermissionUnlocks
workspace:spawnspawnTile, spawnVis, spawnClaude, addFrame, spawnAgent
workspace:closecloseTile
workspace:editrenameTile, openFolder
workspace:promptprompt, and spawnAgent with a prompt (1.4)
workspace:sessionssessions, 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 view

An 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 wroteWhat happens
fetch("./data.json"), XHR of your own filesdeclare "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 filesrefused: every source list names your own origin only
fetch() of anything else / WebSocketrefused, another view's files too. There is no network, by design
<link> to Google Fonts, a CDN scriptloads nothing, no error worth reading
<iframe>frame-src 'none'
require, process, node:*there is no node here
localStorageopaque 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, geolocationrefused — 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, replaySince and history() tell you what happened meanwhile. On an older one you cannot record history while you are not on screen — persist timestamps in setLayout, 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. A planReview tile is a human decision waiting, which usually belongs with "needs you".
  • On arrival, selection carries 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

MistakeFix
Blank canvas, no errorYou drew before await connect(), or you assumed network
Fan spins on an idle workspaceA rAF loop. Use createInvalidator
Unreadable in light modeHardcoded colours. Use --hm-color-*
Terminal appears in the wrong placeRects are viewport pixels, and stale after resize
A closed tile still has a surfaceYou ignored undock, or leaked its status subscription
A widget's "go to", a notification's View or hive ctl focus does nothing in your viewNo onReveal, or it answers without moving to the tile
Something near the camera covers the viewNothing caps its size on screen: see "A 3D view"
Button silently deadCommand 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.