Hive
/Hive
Start, grow and check a claudectl hive across machines. Use when the user wants to start a hive, invite or add a machine or person, join someone's hive, approve a join request, see which machines are connected, share a skill with the hive, or asks why a peer shows no knowledge or will not connect. Covers `claudectl relay` (the connection between machines) and `claudectl hive` (the knowledge shared over it).
- Author
- mercurialsolo ↗
- Repository
- claudectl ↗
- Licence
- MIT
- Last repository change
- 22.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Start, grow and check a claudectl hive across machines. Use when the user wants to start a hive, invite or add a machine or person, join someone's hive, approve a join request, see which machines are connected, share a skill with the hive, or asks why a peer shows no knowledge or will not connect. Covers `claudectl relay` (the connection between machines) and `claudectl hive` (the knowledge shared over it).
Original author description
Start, grow and check a claudectl hive across machines. Use when the user wants to start a hive, invite or add a machine or person, join someone's hive, approve a join request, see which machines are connected, share a skill with the hive, or asks why a peer shows no knowledge or will not connect. Covers `claudectl relay` (the connection between machines) and `claudectl hive` (the knowledge shared over it).
How it works
- First, look
- Start a hive (the host)
- Join a hive (the other machine)
- Approve who gets in (the host)
- Share a skill with the hive
- In the TUI
- When something looks wrong
SKILL.md preview
--- name: Hive description: Start, grow and check a claudectl hive across machines. Use when the user wants to start a hive, invite or add a machine or person, join someone's hive, approve a join request, see which machines are connected, share a skill with the hive, or asks why a peer shows no knowledge or will not connect. Covers `claudectl relay` (the connection between machines) and `claudectl hive` (the knowledge shared over it). version: 0.92.3 --- # claudectl Hive claudectl links machines in two layers. Keep them apart when you explain or act: - **Relay** connects machines: encrypted TCP links made by pairing. It carries work and state: `relay fleet` (every session on every machine), `relay delegate`, `relay send-session`. - **Hive** is the knowledge shared over those links: distilled approve/deny preferences, insights, and skills the user chose to share. Peers gossip it and weight it by trust; local knowledge wins a conflict. The hive needs the relay. The relay does not need the hive. An **unnamed** hive is simply everyone this machine has paired with; naming it gives it membership rules (a join policy) on top of pairing. ## First, look Run these before changing anything, and report what they say: ```bash claudectl --version # both machines should run the same version claudectl hive identity # "unnamed", or the hive's name and join policy claudectl hive status # membership, units, gossip sync per peer claudectl relay peers # paired machines: live / stale / never, last heard, address ``` Is a relay already listening? On macOS the background agent is `io.claudectl.relay`: ```bash launchctl list | grep io.claudectl.relay lsof -nP -iTCP -sTCP:LISTEN | grep claudectl ``` ## Start a hive (the host) 1. Keep a relay running. Prefer the background agent over a foreground `relay serve`, because it survives logout: ```bash claudectl relay install-agent ``` 2. Name the hive. `ask` makes every join wait for the owner's approval, which is the right default when anyone other than the owner will join: ```bash claudectl hive identity set --name <name> --description "<what it is for>" --join-policy ask ``` Never pick `--join-policy open` on your own initiative. It lets any machine that sees the LAN broadcast join without approval. Only set it when the user asks for it by name. 3. Mint an invite and hand it to the user: ```bash claudectl hive invite --words # link, relay code and word phrase claudectl hive invite --qr # QR of the link ``` The invite carries the pairing secret. Give it to the user to pass on privately. Do not post it to a channel, issue, PR or any shared document. ## Join a hive (the other machine) ```bash claudectl hive join <link | relay code | word phrase> claudectl relay install-agent # keep this side's relay up too ``` `hive join` dials the address inside the invite, pairs, records membership and exits. If it cannot reach that address it fails with `connection failed` and saves nothing, so the joiner must be able to reach the host's address as printed in the invite. The joiner then has to dial the host for knowledge to move. `join` prints the line to do it: ```bash claudectl relay connect <host-address>:<port> ``` `relay connect` stays in the foreground to hold the link open and only stops on ctrl-c. Ask the user to run it in its own terminal, or start it as a background command. Never run it inline before other steps: it will not return. `claudectl hive status` then reads `asked to join "<name>" ... awaiting owner approval` until the host approves. To pair a machine without joining a named hive (only to delegate work or move sessions), use `claudectl relay invite` on one side and `claudectl relay join <code>` on the other. ## Approve who gets in (the host) ```bash claudectl hive requests # who is waiting, and who is in claudectl hive requests approve <peer-id> claudectl hive requests deny <peer-id> ``` Approving and denying are the owner's decisions. Show the user the waiting list and let them choose. A denial cannot be undone by the peer asking again, so never deny a request just to clear it. ## Share a skill with the hive ```bash claudectl hive share skill <path/to/SKILL.md> # --scope universal | language:X | project:X claudectl hive shared # what peers have shared claudectl hive pending # received, not yet accepted ``` Installing something a peer shared runs that peer's instructions on this machine. List it with `hive pending` and let the user accept it. ## In the TUI - `p` on the dashboard toggles the peers panel: state, trust, units sent and received, sessions per peer. - `K`, then `Tab`, opens the Hive tab: `h` start listener, `i` invite, `J` join, `r` refresh. - `S` on a session sends that conversation to a paired machine. ## When something looks wrong - **`Address already in use` from `relay serve`.** A relay is already listening, almost always the launchd agent. Nothing to fix. Skip `relay serve` and go on to the invite. - **The invite shows a LAN address and the other person is elsewhere.** A `192.168.x.x` address only works on the same network, and the invite cannot be pointed at another address. Joining with that code fails before anything is saved, and `relay connect` to a Tailscale address afterwards finds no pairing key. Tell the user the joiner has to be on the host's network (or reach that LAN address through a VPN route) when they redeem it. - **A paired peer shows `stale` or `never` in `relay peers`.** Pairing is a stored key and outlives the connection, so a machine that is off, asleep or gone stays listed. The supervisor places no work on it, and `delegate` / `send-session` to it will fail to connect. `claudectl relay prune` lists the ones quiet for a week (`--older-than` to change it); show the user the list and run `--yes` only if they agree. It never removes a peer the hive depends on. - **A peer shows `0 units` and `last sync epoch 0`.** That means nothing has been sent yet, not that the peer is disconnected. Check `relay peers` for a recent heartbeat and `hive requests` on the host for membership. Units only exist once the brain has distilled some decisions. - **Names like `peer-a`, `peer-b`, `host-1`, `ku_local`, `ku_remote` or `ku_1` in `hive status`, `trust.json` or `~/.claudectl/hive/conflicts.jsonl`.** These are test fixtures written by `cargo test` into the real `~/.claudectl` (#603), not peers and not real conflicts. Tell the user. Do not delete them without asking, and back up `~/.claudectl/hive` before anyone does. - **A join between two of the user's own machines is silently closed while both relays run (#608).** Stop the joining machine's relay for the join, then start it again. On macOS the agent is `io.claudectl.relay`; ask the user before stopping it: ```bash launchctl bootout gui/$(id -u)/io.claudectl.relay # stop claudectl hive join <invite> launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/io.claudectl.relay.plist # start again ``` - **A command from this skill is missing.** The machine runs an older claudectl. Compare `claudectl --version` on both sides and upgrade (`brew upgrade claudectl`). Run `claudectl doctor` for a full install and runtime check.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · mercurialsolo/claudectl | 90 | MIT |
| hive-intel/hive-sdk | 100 | MIT |
Database snapshot: 13.11.2026 · package version ead9b4b6493c (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100desktop-shipped-skills
Change the agent skills Hive Desktop ships into an agent workspace — the hive-flows, hive-actions, hive-settings, hive-webhook-sources, hive-mcp, hive-agent-workspaces SKILL.md files. Use when editing what one of those says or adding a new one. - 90hive.writing-hive-skills
Author a new Agent Skill for a Hive agent that conforms to the Agent Skills specification (SKILL.md with YAML frontmatter, optional scripts/references/assets directories). Use when the user asks to create, scaffold, add, install, or package a new skill for a Hive agent, or you… - 90hive.writing-hive-skills
Author a new Agent Skill for a Hive agent that conforms to the Agent Skills specification (SKILL.md with YAML frontmatter, optional scripts/references/assets directories). Use when the user asks to create, scaffold, add, or package a new skill for a Hive agent. - 90Session Monitoring
Provides awareness of claudectl session state, health checks, and cost tracking. Activated when the user asks about session health, spending, brain decisions, or multi-session coordination. - 100hive-tool-discovery
Use this skill when the exact Hive MCP tool, task toolset, provider, endpoint name, schema, operation type, or argument shape is unknown and hive-query routing was not enough — including "what can Hive do", "which provider covers X", "is Hive healthy", or any failed tool-name… - 100hive-setup
Use this skill to install, connect, sign in to, verify or remove Hive in an AI client or shell, or to get an API key for a server or script. Run it yourself with /hive-setup.