hivemind
CLAUDE.md17 starsChanged 12 days agoMITView on GitHub
A multi-session project. Start at docs/plans/multiplayer.md: what is done, what is in progress, how to resume, and the checks to run. The design is docs/design/multiplayer-2026-09-28.md (accepted; Phase 0 refactors R1–R16 come before any feature work) and the facts behind it are in docs/design/multiplayer-2026-09-28-research.md. Update the status table in docs/plans/multiplayer.md in the same commit as the work it describes, so the next session picks up where this one stopped. Its Working rules (modular code, one owner per job, no seams for…
- Commits and pushes
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- guide/AGENTS.mdAGENTS.md
- spec/agents.mdAGENTS.md
- adding-an-agent-providerSkill
- ascii-character-animationSkill
- feature-doneSkill
- hive-browserSkill
- hivemind-custom-viewSkill
- hivemind-live-wallpaperSkill
- maintaining-docsSkill
- test-auditSkill
The file
We split this CLAUDE.md into the rules it gives an agent
8 rules. About 0 are common, 1 is distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 9
Update the status table in docs/plans/multiplayer.md in the same commit as the work it describes, so the next session picks up where this …
- Very specific: line 23
Every test written or changed passes the authoring gate in .claude/skills/test-audit/SKILL.md (the maintainer's rule, adapted from …
- Very specific: line 52
Read it before touching providers/, agents.tsx, or agent-state.ts.
- Very specific: line 122
If the release workflow fails but the tag is pushed: delete the tag (git tag -d vX.Y.Z && git push origin :refs/tags/vX.Y.Z), fix the …
- Very specific: line 139
If you (Claude) made any change that ships to users — code, dependency, install behavior, hive ctl surface — append a one-line entry to …
- Very specific: line 160
When the user asks you to work on an issue (e.g.
- Distinctive: line 170
Do not exit a session silently.
- Very specific: line 174
If $HIVEMIND_TILE is set you are an agent tile and can drive the canvas with hive ctl: spawn and coordinate other agents, read their …
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md 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
CLAUDE
Multiplayer, other devices, phone — work in progress
A multi-session project. Start at docs/plans/multiplayer.md: what is done, what is in
progress, how to resume, and the checks to run. The design is
docs/design/multiplayer-2026-09-28.md (accepted; Phase 0 refactors R1–R16 come before any
feature work) and the facts behind it are in docs/design/multiplayer-2026-09-28-research.md.
Update the status table in docs/plans/multiplayer.md in the same commit as the work it
describes, so the next session picks up where this one stopped. Its Working rules (modular
code, one owner per job, no seams for tests) apply to every item.
Definition of done
A user-facing change is done only when every surface it touches is done: the agent-native CLI,
the app UI, the phone page, the guide and references, agent briefs, READMEs, HiveHub,
hivemind-plugins, local-data migrations, contract versions, security, tests, CHANGELOG and
cleanup. Walk .claude/skills/feature-done/SKILL.md before planning or briefing, and report
against its table.
Tests
Every test written or changed passes the authoring gate in .claude/skills/test-audit/SKILL.md
(the maintainer's rule, adapted from openclaw's test-audit skill), and each new test is shown
to fail when the behaviour it guards is broken.
Work that runs per event
Agent status, terminal output, keystrokes and store changes fire many times a second, on Electron main or the pty daemon's one thread, where every window and terminal waits behind them. Fix the cause, at the owner, not the symptom. Before adding work there, check:
- It does not re-derive from scratch (folder scan, whole-document read or copy, full serialize).
The owner keeps the result and clears it on change (
WorkspaceStore.getCore). - It gives back the same object when nothing changed. Caches, memos and debounced saves key on
identity (
rebaseRecords). - Its cost at 50 tiles, workspaces, board objects or 5000 scrollback lines is measured and stated.
- A heavy resource per item (GL context, process, full read) is spread or bounded, not made N at once.
- A feed, poll or listener stops when its last follower leaves.
Measure the built app before and after, on a real GPU (xvfb renders in software and lies), and put both numbers in the commit.
Writing docs
Writing or editing docs in guide/ — follow .claude/skills/maintaining-docs/.
Adding or completing an agent integration
Wiring a new CLI agent (kiro, gemini, amp, …) — or finishing a half-wired one — follows
the adding-an-agent-provider skill in .claude/skills/adding-an-agent-provider/.
Read it before touching providers/, agents.tsx, or agent-state.ts.
The part people skip: probe the real binary before deciding what it supports. A
provider PR that assumes "no hooks / no session ids" without running --help ships an
agent the control plane cannot drive — hive ctl read times out, hive ctl workflow
gathers nothing, and a tile waiting on approval notifies "Finished". checklist.md next to the
skill is the definition of done; it goes in the PR description.
<!-- release:start -->Release management
This project ships prebuilt binaries via GitHub Releases. End users install with install.sh, which downloads the latest release assets — no toolchain on the user's box. The release pipeline is fully automated; you (Claude or the maintainer) do NOT build locally.
How to cut a release
# from a clean main branch, in sync with origin/main:
./scripts/release.sh # 2026.9.0, 2026.9.1 … then 2026.10.0 — computed, nothing to choose
./scripts/release.sh 2026.9.4 # explicit version
./scripts/release.sh --dry-run # preview without writingWhat it does (scripts/release.sh):
- Pre-flight: rejects a dirty tree, requires
main, requires sync withorigin/main. - Bumps
versionin every workspacepackage.jsonin lockstep. - Inserts a
[X.Y.Z] — YYYY-MM-DDsection intoCHANGELOG.mdunder[Unreleased]. - Commits
chore(release): vX.Y.Zand creates an annotated tag. - Pushes branch + tag → fires
.github/workflows/release.ymlon GitHub Actions.
What the workflows do
.github/workflows/ci.ymlruns on every push tomainand PR: typecheck of every package + build + unit tests (the desktop'spnpm test:unit, then every package's and the CLI'sbun testthroughpnpm test). Heavy Playwright e2e is intentionally NOT run here — release builds validate the full build path..github/workflows/release.ymlruns onv*.*.*tags (and manualworkflow_dispatch). Parallel build jobs:build-linux(ubuntu) →hive-linux-x86_64+hivemind-<version>-x86_64.AppImage;build-linux-arm64(ubuntu-24.04-arm) →hive-linux-arm64only (a remote-machine CLI, no desktop);build-macos(macos-26, Apple Silicon) →hive-darwin-arm64+hivemind-<version>-arm64-mac.zip;publishdownloads their artifacts and creates the GitHub Release. A manualworkflow_dispatchis BUILD-ONLY unless you pass-f publish=true— usegh workflow run release.yml --ref <branch> -f tag=vX.Y.Z-testto smoke-test a platform's build without cutting a release; the assets land as run artifacts. Each build job compiles the CLI withbun build --compile(no--target— host arch; the Linux jobs then runapps/cli/tests/sessions.test.tsagainst the binary viaHIVE_BIN, so a broken embedded pty addon fails the release), builds the renderer + main withelectron-vite, then packages viapnpm deploy+electron-builder.build-hive-netis a matrix over the four targets (hive-net-linux-x86_64,hive-net-linux-arm64,hive-net-darwin-arm64,hive-net-windows-x64.exe;cargo build --release --lockedincrates/hive-net), each smoke-tested by checkinghive-net idagainstconformance/identity.json. The app,hive hostand hive-net speak one daemon protocol and must come from one release (a mismatched pair stops and says so), so the Linux and macOS targets are required: a failure there holds the release. The Windows target stayscontinue-on-error, as the Windows app does;install.sh/install.ps1still warn and install the rest when a hive-net asset is missing. CI'shive-netjob runs the crate's tests.Windows specifics:
build-windows(windows-latest) produceshive-windows-x64.exe+hivemind-<version>-x64-win.zip, both published. The job stayscontinue-on-error: truewhile being inpublish'sneeds: publish waits for it, but a Windows failure ships the release without its assets instead of holding Linux and macOS back. Its smoke steps run the build rather than only packaging it — the compiled CLI, a ConPTY spawn, a bare.cmdagent throughresolveWindowsSpawn, the app opening its named pipe, and a hook throughcmd.exeasserting env + stdin arrive. The job also parse-checksinstall.ps1(the only Windows host the project has) and asserts the unpackedwin32-x64conpty.node+conpty.dllmade it into the bundle (Windows drives ConPTY — there is nopty.node, and a.dllis not covered by electron-builder's implicit native-module unpacking), because nothing else fails when the native module is missing or wrong-arch.macOS specifics worth not re-deriving: we have no Apple Developer cert, so
mac.identityisnull(electron-builder skips signing entirely — it does NOT fall back to ad-hoc). An arm64 bundle with an invalid signature is SIGKILLed by the kernel, and electron-builder's repack invalidates the signature Electron ships with — so the workflow re-applies an ad-hoc signature (codesign --force --deep --sign -) and archives withditto(preserves the framework symlinkszipmangles). Users still hit Gatekeeper quarantine;install.shstrips the xattr. Only arm64 is published: the bundle carries a host-arch@lydell/node-pty, so cross-arch packaging would ship the wrong native module. Intel macs use--dev..github/workflows/nightly.ymlruns daily at 03:17 UTC and by manual dispatch. It pins the currentmainSHA and calls the samerelease.ymlbuild and smoke jobs, publishingnightly-YYYYMMDD-RUN_IDas a pre-release withmake_latest: false. Stablereleases/latestremains stable.bash install.sh --channel nightlyorinstall.ps1 -Channel nightlyinstalls the newest nightly; later upgrades and the app's update check follow that channel. Pass--channel stable/-Channel stableto switch back. Nightly discovery uses GitHub's releases API, so it can be rate-limited.--version <tag>/-Version <tag>(orHIVEMIND_VERSION) installs exactly that build, older ones too, which is the rollback;--channel stablefrom a nightly installs the latest stable even though the nightly is newer. Theprunejob keeps the 14 newest nightlies and deletes older ones with their tags.- Release builds cache the pnpm store, Electron downloads and electron-builder tools.
hive-net's Cargo cache is saved by the nightly only (a cache saved under a tag is never read again) and restored by tag runs; its release profile has no cross-crate LTO, which made the build slow for a slightly smaller binary. The phone page restores ci.yml's cache. The Windows zip uses Deflate level 5 instead of the package's maximum, which took 23 minutes on that zip alone (run 37036151192). All binary and app smoke checks still run. - CI (
ci.yml) skips hive-net, hive-phone and compose when the files each one reads already passed (a hash of them, saved as an empty cache entry on success; every job still runs at least weekly), runs hive-net's tests with cargo-nextest, and splits the unit tests intodesktopandpackagesunder the requiredbuild-and-testcheck. The repository's Actions cache is capped at 10 GB and fills up: keep cache keys stable and save from main only where a run on another ref would never read it.
Pre-release checklist
Before running ./scripts/release.sh:
- All e2e tests green locally:
apps/desktop/scripts/e2e.sh(every spec must pass; the profile is isolated per run — see apps/desktop/AGENTS.md). Run this on a quiet machine. The suite takes 8-16 minutes and launches Electron at least once per spec; at system load 25-30 on 16 CPUs a rotating handful of specs fails on cold-boot and timing, every one of which passes in isolation. Checkuptimefirst — a red run on a loaded box is not evidence of a regression. - Canvas perf unchanged within noise vs the previous release:
apps/desktop/scripts/perf-canvas-effects.mjs. Measure on a real display with the backend recorded — absolute FPS, frame-time and latency gates are not valid under xvfb, which renders on the llvmpipe CPU rasterizer; seedocs/design/performance-native-2026-09-09.md. On a live desktop a capped run can read ~1 FPS for anything that moves while the page's main thread sits idle — each present waiting on a vsync that does not arrive. Run the A/B uncapped (PERF_EXTRA_ARGS="--disable-gpu-vsync --disable-frame-rate-limit") and check the recordedsession.type— after a reboot the desktop may be Wayland, not the X display you expect (docs/design/perf-streaming-2026-09-11.md). - Unit tests green:
pnpm test:unitfromapps/desktop. - Installer tests green:
bash scripts/install-plan-test.sh+bash scripts/install-macos-test.sh+bash scripts/install-staged-test.sh. The first asserts the release-asset names install.sh asks for match what release.yml uploads — a rename on either side breaks every install. The second drives the real Darwin helpers withditto/xattrshimmed, so the mac path is covered without a mac, including an update taken while the app is open, which goes in place ofhivemind.apponce it quits. The third drives the same on Linux: each version a folder of its own, and the launcher starting the one installed last. - A change to what is on disk ships a numbered migration in
packages/hive-core/src/migrations/(added tolist.ts), tested on a fixture of old-shaped data, killed at 20 points and run again (fixtures/runs.ts). A migration six months old is deleted with its fixture. - CHANGELOG
[Unreleased]section has at least one entry describing the user-visible change. - No uncommitted changes (
git statusclean).
Debugging a failed release workflow
gh run list --limit 5 --json status,conclusion,name,databaseId # find failed run id
gh run view <id> --log-failed | tail -50 # tail the error
gh run rerun <id> # retry (rare)Common failure modes seen so far:
- "package.json must be under apps/desktop" — electron-builder rejects pnpm symlinks to sibling workspace packages. Fixed by
pnpm --filter @hivemind/desktop deploy desktop-deployBEFORE running electron-builder inside the deploy dir. - "Cannot compute electron version" —
pnpm deploy --prodstrips devDeps (including electron itself). Usepnpm deploy --legacywithout--prod. - "Multiple versions of pnpm specified" —
pnpm/action-setupshouldn't pinversionwhenpackageManageris set in rootpackage.json.
If the release workflow fails but the tag is pushed: delete the tag (git tag -d vX.Y.Z && git push origin :refs/tags/vX.Y.Z), fix the workflow, re-tag.
Versions
Calendar versions: YYYY.M.N, the Nth release of that month, counting from 0 (2026.9.0,
2026.9.1, then 2026.10.0). The script computes it, so there's no bump to decide. It is still a
valid semver (no leading zeros), which npm, electron-builder and the update check need, and it
sorts above every 1.x release.
The version number says when, not what broke. Compatibility lives in the contracts that
have their own version — the view protocol (PROTOCOL_VERSION), agent manifests
(manifestVersion), package bundles (apiVersion), settings.json (v) — and a plugin that needs
a newer app says so with minAppVersion. A change that breaks any of them, the hive CLI or a
hive ctl --json shape starts its CHANGELOG line with Breaking:.
Hand-off rule
If you (Claude) made any change that ships to users — code, dependency, install behavior, hive ctl surface — append a one-line entry to CHANGELOG.md under ## [Unreleased] BEFORE handing the session back. The maintainer can then cut a release with ./scripts/release.sh and the changelog is ready.
<!-- release:end --><!-- hivemind:agentic:start -->Agentic mode — the hive CLI
This workspace tracks issues under .hivemind/ and is driven through the hive
CLI (on PATH). Use it from Bash — there is no MCP server. Every command takes
--json for machine-readable output; every id from another registered repo
resolves automatically.
hive show <id> --json— load an issue (title, description,acceptanceCriteria, activity).hive list --state todo --json— issue summaries, filterable by state / label / assignee.hive ctl set-state <id> in_progress --note "…"— backlog | todo | in_progress | in_review | done | cancelledhive ctl add-comment <id> "…"·hive ctl mark-acceptance <id> <index>(0-based;--undonereopens)hive update <id> --title … --assignee claude --assignee-type agent·hive new "Title" --parent <id>hive ctl delete-issue <id>— destructive; only on an explicit ask.
Execution contract (REQUIRED)
When the user asks you to work on an issue (e.g. PAY-42):
hive show PAY-42 --json→ load context.- Claim it:
hive ctl set-state PAY-42 in_progress+hive update PAY-42 --assignee claude --assignee-type agent. - Plan briefly (one comment via
hive ctl add-comment). - Execute. Tick each criterion as you go (
hive ctl mark-acceptance PAY-42 <n>). - Comment progress at meaningful checkpoints (file:line refs).
- Every session MUST end with
hive ctl set-state—in_review(done, awaiting review),done(only with explicit authority),in_progress(will resume), orcancelledwith--note.
Do not exit a session silently.
Multi-agent control plane (when running inside hivemind)
If $HIVEMIND_TILE is set you are an agent tile and can drive the canvas with
hive ctl: spawn and coordinate other agents, read their replies, run
fanout / pipeline / mapreduce workflows, supervise + approve, and report back to
the agent that spawned you. The hivemind skill in .claude/skills/hivemind/
has the exact commands; hive ctl --help lists them.
<!-- hivemind:agentic:end -->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.

