Hive - Agent Communication Base Layer

Hive CLI is a required external dependency. Installation methods:

bash

pipx install git+https://github.com/notdp/hive.git
npx skills add https://github.com/notdp/hive -g --all
# Upgrade CLI:
pipx upgrade hive
# Upgrade global skills (for users who installed from GitHub):
npx skills update hive -g
# Refresh for local repo checkout (skills lock does not track local sources, update is not available):
npx skills add "$PWD" -g --all

Upgrading the Hive CLI will not automatically refresh the installed

hive

skill; when the skill is outdated, running the

hive

command in the agent pane will receive a stderr reminder, or you can explicitly run

hive doctor --skills

to view details.

Run

hive --help

to confirm successful installation.

You are an agent running in Hive. Hive is your collaborative runtime, not a specific workflow. The map of this skill:

Startup — One command:
```
hive init
```
Command Quick Reference — Daily-used CLI +
```
hive team
```
field semantics
Messaging Mechanism — How to receive, send, thread / root protocol / shell security (active-turn fork and handoff are covered in
```
references/advanced-routing.md
```
)
Collaboration Rules — What to resolve within the team, what to escalate to users
Workflow Loading — Stack higher-level processes (such as code-review) on top of Hive
Troubleshooting + Protocol Boundaries — See
```
references/debug.md
```

Startup

First thing after loading the hive skill: run
hive init
, then follow the CLI output.

hive init

is idempotent; errors will tell you what's missing — run

hive team

only after it completes.

Loading the hive skill means you are entering a peer group (a basic collaboration mode parallel to the

/gang

gang group; two agents verify / review / confirm each other).

hive init

will automatically configure an idle alien (different model-family) peer pane for you — it will first look for an existing one in the same tmux session, and if not found, spawn one on the spot in the current window. Both panes will be tagged with

@hive-group=peer

, which is directly visible in

hive team

Command Quick Reference

bash

hive team                            # Members + runtime(inputState/busy/turnPhase) + peer + group; `self` is a string referring to your own member name
hive send dodo "see attachment" --artifact /tmp/file.md   # When the file already exists
hive send dodo "see attachment" --artifact - <<'EOF'
# Findings
- item
EOF
hive reply dodo "ack, looking"       # Reply to dodo's latest message sent to you (auto reply-to)
hive answer claude "yes"             # Answer an agent's pending question
hive notify "Press Space to talk to me"      # Send a desktop notification to the user of the current pane
# Use notify only when you are blocked and require user intervention; copy structure: what happened / why you are needed now / what to do after pressing Space to return

What does

hive team

return?

Find your own entry in

members

self

and check the full status. Field meanings:

self
— String = your own member name (board/terminal panes do not have runtime fields like
```
model
```
/
```
sessionId
```
/
```
turnPhase
```
, nor will they forge them)
group
— Appears on the member line only when the pane is tagged with
```
@hive-group
```
(example: peer group member
```
group: peer
```
)
inputState=waiting_user
— The other party is waiting for an answer; use
```
hive answer
```
to respond
busy=true/false
— A second-level activity boolean at the tmux output layer, not equivalent to semantic busy/idle
turnPhase
— This is the transcript/JCL semantic layer indicating "whether it's easy to interrupt the other party by inserting a new root now"

Messaging Mechanism

Receiving Messages

Messages from other agents appear in your pane as

<HIVE from=... to=... msgId=... artifact=<path>>body</HIVE>

blocks — this is the main channel. The block itself contains everything you need:

The short body (sender's summary) is between the tags
Detailed content is in the file pointed to by
```
artifact=<path>
```
; use the Read tool to open that path for the full text

Always read the original text in the
<HIVE>
block.

hive thread <msgId>

and

hive delivery <msgId>

are troubleshooting entry points (see

references/debug.md

) and are not used by agents for daily message reception.

send vs reply (thread model)

Hive's messages are organized into threads. Before sending a message, ask yourself: Is this a new topic, or a continuation of an existing thread?

New topic →
hive send
(new task / new report / new question / new discovery, start a new thread)
Direct response to inbound →
hive reply
(answer to the other party's question, ack for what the other party asked you to do, continue the thread)

The judgment point is "whether the content is a response to that inbound message", not "whether you have an inbound message on hand". Typical pitfalls:

dodo just sent you "Ready" (inbound in inbox)
You now want to assign dodo a new task "review PR #123"
- Wrong:
```
hive reply dodo "review PR #123"
```
  → autoReply is attached to "Ready", polluting the thread
- Correct:
```
hive send dodo "review PR #123"
```
  → start a new thread for the new task

hive send

The only entry point for starting a new thread; does not accept

--reply-to

. The body is a short summary; use

--artifact

when it can't fit (see root protocol below). Even if the other party just sent you an inbound message, use

send

if what you want to say is a new topic.

hive reply

Continue a thread. If

--reply-to

is not passed, Hive will select "the latest inbound message from that agent that you haven't replied to yet" as the anchor. autoReply only saves the step of finding the msgId, but does not judge whether the content actually continues — still use

send

for new topics.

Scenarios for explicitly passing

--reply-to <msgId>

When prompted during handoff / spawn, you are directly given the anchor msgId (you don't have that inbound message on hand)
You want to bypass the default autoReply selection and reply to an earlier thread

Hive strictly locks replies within the same thread; it will directly report an error if there is no inferable inbound message and you haven't passed

--reply-to

Root Protocol (send body constraints)

The
```
body
```
of a root send (without
```
--reply-to
```
) is always a short summary; detailed content is placed in
```
--artifact
```
```
--artifact
```
is not mandatory — single-line confirmations like "ack", "Ready", "task done" can be sent as root sends without artifact. Use artifact when there is more information
The
```
body
```
will be directly rejected if it meets any of the following conditions, and must be moved to artifact:
- Exceeds
```
500
```
  characters
- Has
```
3
```
  or more lines in total
- Contains fenced code:
```
```
```
- Any non-empty line starts with
```
#
```
  ,
```
-
```
  , or
```
*
```

Preferred method: heredoc + stdin artifact:

bash

hive send <name> "<message>" --artifact - <<'EOF'
# Findings
- item
EOF

Quoted
```
EOF
```
tags do not perform shell interpolation; markdown / code blocks / quoted content are passed as-is
```
printf '%s\n' ... | hive send ... --artifact -
```
is only an alternative, with more escaping pitfalls
Multi-line markdown / code should use heredoc +
```
--artifact -
```
; command substitution like
```
$(cat <<EOF ...)
```
has deeper shell escaping pitfalls, heredoc is the only safe path
```
reply
```
is not subject to this root protocol; you can just reply with a short text
When the target is in active turn, root send will automatically fork a clone to take over (
```
routingMode=fork_handoff, routingReason=active_turn_fork
```
); there is no longer a
```
deferred
```
state. See "busy-fork routing" below for details.

Busy-Fork Routing (Summary)

When an unfamiliar sender sends a root send to a target that is in active turn, the message will be automatically forked to a clone pane (

<target>-c1

) to take over — this is not a bug, but an expected protection mechanism. Peer pairs and owner-parent/child (bidirectional) are bypass-exempt and can directly reach the original target.

Complete 3 bypass criteria + clone pane behavior + board pane file channel exceptions →

references/advanced-routing.md

Shell Security

Backticks(```````) in the body of

hive send

and

hive reply

will be executed as command substitution by zsh/bash first, silently corrupting the message. When including markdown inline code, use heredoc +

--artifact -

, or wrap the entire body in single quotes.

First Reply When Taking Over an Existing Thread

When spawned / handed off to a thread that is not your own, the taker must explicitly use
--reply-to <msgId>
; see

references/advanced-routing.md

for details.

Collaboration Rules

Team First, User Second

The collaboration order is fixed: Resolve the problem within the team first, then report to the user. Before turning to the user, run

hive team

first to see if there is a suitable peer to take over.

When discussing with peers, the goal is to converge the conclusion within the team. Only provide three things to the user:

Converged conclusion
A single blocking issue that has not been converged and truly hinders progress
Your suggested next steps

Oscillating A/B/C options, intermediate disagreements among peers, vulnerabilities you plan to go back and challenge further — all should be resolved within the team before presenting to users. If a peer's argument has flaws, first point it out to the peer and converge, handle it yourself before reporting to the user (unless the user explicitly requests to see the original discussion process).

Only escalate to the user in the following 4 cases:

Checked
```
hive team
```
and no suitable agent can take over
The decision involves irreversible external side effects (
```
git push
```
, sending PR comments, deleting data, running migrations, notifying external systems)
Need the user to provide information, authorization, or preferences that all agents in the team do not have
The user explicitly requests to participate in such decisions

The escalation wording is fixed: "Have checked hive team first; this step still requires your decision because ..." — directly provide the conclusion and problem. "Who to assign to take over" is your judgment, not the user's decision.

Whoever Proposes the Solution Implements It

After converging with peers, the final adopted solution is implemented by the proposer, and reviewed by the other party.

Default Division of Labor

Claude focuses on front-end experience, copy convergence, and divergent discussions; GPT focuses on backend correctness, constraint checking, and rigorous review. If the project has more clear candidates or team experience, follow the project facts.

Workflow Loading

Higher-level processes (such as

code-review

) are loaded on top of Hive:

Orchestrator executes
```
hive workflow load <agent> code-review
```

Or use

hive spawn <agent> --workflow code-review

during spawn

After loading the workflow, continue using Hive commands as the base for communication and status.

Troubleshooting + Protocol Boundaries

Troubleshooting command list (

hive doctor

delivery

thread

capture

inject

interrupt

kill

exec

) + protocol hard constraints (sending entry points, prerequisites for

hive answer

, non-strict reliable queue semantics, division of labor between

gh

and

hive

kernels) →

references/debug.md

. No need to read this for daily message sending and receiving; see the "Messaging Mechanism" section above for the main channel.

hive

NPX Install

Tags

SKILL.md Content (Chinese)

Hive - Agent Communication Base Layer

Startup

Command Quick Reference

What does
`hive team`
return?

Messaging Mechanism

Receiving Messages

send vs reply (thread model)

`hive send`

`hive reply`

Root Protocol (send body constraints)

Busy-Fork Routing (Summary)

Shell Security

First Reply When Taking Over an Existing Thread

Collaboration Rules

Team First, User Second

Whoever Proposes the Solution Implements It

Default Division of Labor

Workflow Loading

Troubleshooting + Protocol Boundaries