agentleFS
dip497dip497/hivemind/CLAUDE.md

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

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
  1. Very specific:

    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 …

    line 9
  2. Very specific:

    Every test written or changed passes the authoring gate in .claude/skills/test-audit/SKILL.md (the maintainer's rule, adapted from …

    line 23
  3. Very specific:

    Read it before touching providers/, agents.tsx, or agent-state.ts.

    line 52
  4. Very specific:

    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 …

    line 122
  5. Very specific:

    If you (Claude) made any change that ships to users — code, dependency, install behavior, hive ctl surface — append a one-line entry to …

    line 139
  6. Very specific:

    When the user asks you to work on an issue (e.g.

    line 160
  7. Distinctive:

    Do not exit a session silently.

    line 170
  8. Very specific:

    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 …

    line 174

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

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

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 writing

What it does (scripts/release.sh):

  1. Pre-flight: rejects a dirty tree, requires main, requires sync with origin/main.
  2. Bumps version in every workspace package.json in lockstep.
  3. Inserts a [X.Y.Z] — YYYY-MM-DD section into CHANGELOG.md under [Unreleased].
  4. Commits chore(release): vX.Y.Z and creates an annotated tag.
  5. Pushes branch + tag → fires .github/workflows/release.yml on GitHub Actions.

What the workflows do

  • .github/workflows/ci.yml runs on every push to main and PR: typecheck of every package + build + unit tests (the desktop's pnpm test:unit, then every package's and the CLI's bun test through pnpm test). Heavy Playwright e2e is intentionally NOT run here — release builds validate the full build path.
  • .github/workflows/release.yml runs on v*.*.* tags (and manual workflow_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-arm64 only (a remote-machine CLI, no desktop); build-macos (macos-26, Apple Silicon) → hive-darwin-arm64 + hivemind-<version>-arm64-mac.zip; publish downloads their artifacts and creates the GitHub Release. A manual workflow_dispatch is BUILD-ONLY unless you pass -f publish=true — use gh workflow run release.yml --ref <branch> -f tag=vX.Y.Z-test to smoke-test a platform's build without cutting a release; the assets land as run artifacts. Each build job compiles the CLI with bun build --compile (no --target — host arch; the Linux jobs then run apps/cli/tests/sessions.test.ts against the binary via HIVE_BIN, so a broken embedded pty addon fails the release), builds the renderer + main with electron-vite, then packages via pnpm deploy + electron-builder. build-hive-net is 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 --locked in crates/hive-net), each smoke-tested by checking hive-net id against conformance/identity.json. The app, hive host and 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 stays continue-on-error, as the Windows app does; install.sh / install.ps1 still warn and install the rest when a hive-net asset is missing. CI's hive-net job runs the crate's tests.

    Windows specifics: build-windows (windows-latest) produces hive-windows-x64.exe + hivemind-<version>-x64-win.zip, both published. The job stays continue-on-error: true while being in publish's needs: 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 .cmd agent through resolveWindowsSpawn, the app opening its named pipe, and a hook through cmd.exe asserting env + stdin arrive. The job also parse-checks install.ps1 (the only Windows host the project has) and asserts the unpacked win32-x64 conpty.node + conpty.dll made it into the bundle (Windows drives ConPTY — there is no pty.node, and a .dll is 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.identity is null (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 with ditto (preserves the framework symlinks zip mangles). Users still hit Gatekeeper quarantine; install.sh strips 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.yml runs daily at 03:17 UTC and by manual dispatch. It pins the current main SHA and calls the same release.yml build and smoke jobs, publishing nightly-YYYYMMDD-RUN_ID as a pre-release with make_latest: false. Stable releases/latest remains stable. bash install.sh --channel nightly or install.ps1 -Channel nightly installs the newest nightly; later upgrades and the app's update check follow that channel. Pass --channel stable / -Channel stable to switch back. Nightly discovery uses GitHub's releases API, so it can be rate-limited. --version <tag> / -Version <tag> (or HIVEMIND_VERSION) installs exactly that build, older ones too, which is the rollback; --channel stable from a nightly installs the latest stable even though the nightly is newer. The prune job 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 into desktop and packages under the required build-and-test check. 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. Check uptime first — 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; see docs/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 recorded session.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:unit from apps/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 with ditto/xattr shimmed, so the mac path is covered without a mac, including an update taken while the app is open, which goes in place of hivemind.app once 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 to list.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 status clean).

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-deploy BEFORE running electron-builder inside the deploy dir.
  • "Cannot compute electron version" — pnpm deploy --prod strips devDeps (including electron itself). Use pnpm deploy --legacy without --prod.
  • "Multiple versions of pnpm specified" — pnpm/action-setup shouldn't pin version when packageManager is set in root package.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 | cancelled
  • hive ctl add-comment <id> "…" · hive ctl mark-acceptance <id> <index> (0-based; --undone reopens)
  • 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):

  1. hive show PAY-42 --json → load context.
  2. Claim it: hive ctl set-state PAY-42 in_progress + hive update PAY-42 --assignee claude --assignee-type agent.
  3. Plan briefly (one comment via hive ctl add-comment).
  4. Execute. Tick each criterion as you go (hive ctl mark-acceptance PAY-42 <n>).
  5. Comment progress at meaningful checkpoints (file:line refs).
  6. Every session MUST end with hive ctl set-state — in_review (done, awaiting review), done (only with explicit authority), in_progress (will resume), or cancelled with --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 -->

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.