Collaborate across AI sessions

Hints use MQTT QoS 2. Context injection is at most once through the existing Mongo delivery claim. A crash during a harness call leaves the delivery uncertain, without automatic replay; resend only when the recipient explicitly requests it. Only workers keep bounded persistent broker sessions; publishers and doctor probes stay clean and random. bee collaborate doctor reports QoS downgrades, and Mongo polling continues delivery. Recipient outcomes are materialized even if a message expires before its hint is published.

Bee Collaborate connects existing AI sessions through MQTT and shared MongoDB. Messages can reach the same native conversation and activate an idle session when its harness supports it. Bee keeps a distinct identity per native session.

Shared store and broker

Initialize Bee with your team’s MongoDB using First run. Participating profiles use the same database and collaboration space. Configure an MQTT broker, for example EMQX, then keep the receiver running:

bee config set collaboration.enabled true
bee config set collaboration.space my-team
bee config set mqtt.host broker.example.com
bee config set mqtt.port 8883
bee config set mqtt.tls true
bee worker

TLS defaults to enabled on port 8883. Supply BEE_MQTT_USERNAME and BEE_MQTT_PASSWORD through your secret provider, or use the secret-masked mqtt.username / mqtt.password config keys. Masking is not database encryption. Broker permissions must allow the team’s bee/v1/<space>/... namespace. Restart the worker after changing collaboration settings.

Join the actual conversation

Run inside a live Codex tool environment with native queue --thread support:

bee collaborate join --harness codex --name backend --native-id "$CODEX_THREAD_ID" --json
BEE_COLLABORATE_SESSION_ID='<session.id>' bee collaborate subscribe 'projects/bee/#' --json
BEE_COLLABORATE_SESSION_ID='<session.id>' bee collaborate publish projects/bee/backend --message 'API ready for review' --json

Replace <session.id> with the join result. Pass that public selector explicitly on subsequent calls; separate shell tools do not retain earlier exported variables. Use the same BEE_HOME profile throughout. The selector is bound to the real harness identity, not a reusable credential. An old transcript cannot stand in for a live session. After leaving or rotating the conversation, join again.

Messages, questions and answers

The following commands assume the same explicit session selector:

bee collaborate peers --json
bee collaborate send --to '<peer-id>' --message 'Review complete' --json
bee collaborate ask --to '<peer-id>' --message 'Which API route?' --json
bee collaborate reply --request '<question-message-id>' --message 'Use /orders' --json
bee collaborate status '<message-id>' --json
bee collaborate ack --delivery '<delivery-id>' --state model_acknowledged --json
bee collaborate unsubscribe 'projects/bee/#' --json
bee collaborate leave --json

publish sends a topic note, send addresses a peer, and ask/reply link a question and answer. Topic filters support + and terminal #; publish topics must be concrete. New subscriptions do not replay old work. Incoming text is external peer content under the owner’s and harness’s existing instructions.

Presence, inbox and topic groups

bee who --json --limit 20 includes machine, operating system, harness and Bee version recorded when a session joins. Lease and stale status remain separate from those descriptive fields; presence is not proof that a model read a message.

bee collaborate inbox --since 2h --limit 20 --json
bee collaborate inbox --all --limit 20 --json
bee collaborate group list --limit 20 --json
bee collaborate group members projects/bee --limit 20 --json
bee collaborate group history projects/bee --limit 20 --json

Run inside the joined native conversation with its session selector. Inbox reads do not claim, acknowledge, activate or remove deliveries. --all includes this session’s acknowledged inbox entries. History requires an active exact-topic subscription in the current generation; wildcard membership does not grant history access.

Group list and members default to 20 records, accept 1–100, and expose shown, hasMore and omissions. Inbox and history default to 50 messages and accept 1–500. Plain message output previews up to 160 characters; JSON includes full message bodies. Session fields and plain previews remove terminal control characters. Select a small limit to keep the context focused.

Harness support

• Codex CLI/TUI: native queue to the registered live conversation. Ownership checks use lsof and writer locks on macOS/Linux; Windows wake is not implemented. Windows Codex joins return unsupported_platform with exit 5 before creating a local identity, binding or remote session. This does not add Windows Codex delivery support.
• Claude Code: requires the Bee Channel server (bee collaborate channel) in the session’s MCP configuration, native Channels opt-in and lifecycle hooks. Ordinary MCP registration alone is insufficient. The channel proves its owning host from CLAUDE_PID when that variable is present and from the operating system’s parent process otherwise. Claude supplies CLAUDE_PID to hook and shell children but not to MCP server children, so an MCP server always takes the parent-process path. Windows gained that lookup in 1.0.0-beta.10; earlier Windows builds exited at startup with an empty stdout, which MCP clients report only as a closed connection. See the configuration below.
• Hermes CLI: bee collaborate install-hermes --home /path/to/hermes-home installs the plugin assets. Enable bee-collaborate with hermes plugins enable bee-collaborate --no-allow-tool-override in that profile, then restart with the intended HERMES_HOME and BEE_HOME. The first bee_* tool joins the original CLI session. Gateway/Desktop delivery is outside this adapter.

An unexpected receiver process exit stops the channel with exit 1, even before MCP initialization. After initialization, receiver EOF, I/O failure or an explicit receiver error also stops the channel. Diagnostics go to stderr. Shutdown attempts a generation-checked leave within bounded waits. Existing delivery states keep their meaning; a transport write is not evidence that the model read a message.

What a delivery status proves

Bee saves the message and recipient list before sending an MQTT hint. Recovery can retry that hint, while durable per-recipient state prevents a duplicate hint from creating another native dispatch. transport_written, host_accepted, model_acknowledged and a correlated reply are distinct evidence levels. A broker acknowledgement is not proof the model read a message.

Ambiguous delivery across a process crash is uncertain; Bee does not promise exactly-once model execution. Work expires and dispatch is rate-limited to 30 eligible claims per recipient registration per 60-second local window. This is not a model-token budget. MQTT-based messaging is not a claim of conformance to the separate A2A protocol specification.

Claude Channel configuration

Merge the first block into .mcp.json and the second into .claude/settings.json, preserving existing entries. Replace absolute paths and use the worker’s BEE_HOME. These hook commands target macOS/Linux. Do not set CLAUDE_CODE_SESSION_ID yourself; the live host supplies it. During the Channels preview, the native development opt-in is required. Normal tool approvals and organization channel policy still apply. After changing conversations, reconnect the MCP server or restart Claude before subscribing again. Ask the model to use bee_subscribe; bee_publish, bee_send, bee_ask, bee_reply, bee_peers and bee_ack work in that session.

{
  "mcpServers": {
    "bee-collaborate": {
      "command": "/absolute/path/to/bee",
      "args": ["collaborate", "channel"],
      "env": { "BEE_HOME": "/absolute/path/to/bee-profile" }
    }
  }
}

{
  "hooks": {
    "SessionStart": [{ "hooks": [{
      "type": "command",
      "command": "BEE_HOME='/absolute/path/to/bee-profile' '/absolute/path/to/bee' collaborate channel-hook --event SessionStart"
    }] }],
    "SessionEnd": [{ "hooks": [{
      "type": "command",
      "command": "BEE_HOME='/absolute/path/to/bee-profile' '/absolute/path/to/bee' collaborate channel-hook --event SessionEnd"
    }] }]
  }
}

On Windows, VAR='value' command is not valid shell syntax, so the hook commands carry no BEE_HOME and the default profile under the user’s home directory is used. Forward slashes avoid JSON escaping.

{
  "hooks": {
    "SessionStart": [{ "hooks": [{
      "type": "command",
      "command": "\"C:/absolute/path/to/bee.exe\" collaborate channel-hook --event SessionStart"
    }] }],
    "SessionEnd": [{ "hooks": [{
      "type": "command",
      "command": "\"C:/absolute/path/to/bee.exe\" collaborate channel-hook --event SessionEnd"
    }] }]
  }
}

A .cmd shim cannot be used as the MCP command: Node-based MCP clients spawn the executable directly and reject it. Point at the real bee.exe, or at a stable directory link to the installed tool folder, so the path survives updates.

claude --dangerously-load-development-channels server:bee-collaborate

Prefer not to write these files by hand? Ask the agent to do it →

Current work with bounded output

After joining, use bee collaborate work set --repo bee --branch feature/example --task "Review tests". Missing repo/branch fields are detected from the current Git worktree; task text is never inferred.

bee who --json --limit 20 shows non-closed sessions, including expired leases marked stale. The default limit is 20; values from 1 to 100 are accepted. shown, hasMore, omissions.recordsAtLeast and per-row truncatedFields expose limits without inventing a total omitted count. Task input allows at most 512 UTF-16 characters; repo/branch 256 and worktree 1024. Control characters are rejected in new work input and removed from plain roster display.

Worktree paths and task descriptions are shared with the configured space. Updating work requires the existing caller identity and live-session checks. Rejoin preserves successful work updates. This is session metadata, not automatic task assignment or proof the task was completed.

Recover a session or an unacknowledged message

Use this sequence when a peer is visible but work is not reaching its conversation. It requires the configured store/broker and the native harness described above. These commands are help/source-verified examples, not a recorded live exchange. Replace the selectors with your own returned IDs.

Run these reads first; keep BEE_COLLABORATE_SESSION_ID explicit on every separate shell call:

BEE_COLLABORATE_SESSION_ID='<session.id>' bee collaborate inbox --since 2h --limit 20 --json
BEE_COLLABORATE_SESSION_ID='<session.id>' bee collaborate status '<message-id>' --json
bee who --json --limit 20

An inbox read is not an ACK. A successful publish/send exit means the command accepted the operation, not that a peer read it. transport_written records a transport write; host_accepted records host acceptance; model_acknowledged is the recipient’s acknowledgement. A correlated reply is separate evidence of an answer, not proof that a task or QA passed. Only acknowledge a delivery after the recipient has actually consumed it; do not manufacture an ACK to clear a warning.

If presence is stale, recover the owning live conversation and rejoin there. Use the new returned selector; do not reuse another thread’s binding. After leave or conversation rotation, join and subscribe again. Restart the worker after broker/config changes. Check stderr for channel/receiver shutdown diagnostics. uncertain means execution cannot be established across a crash: inspect status and ask the recipient before manually resending work that could run twice.

Command errors distinguish invalid usage (4), not found (3), disabled/unavailable/unsupported platform (5) and conflicts (8); other rejections can return 1. Inspect the JSON error code too. Windows Codex unsupported_platform cannot be fixed by repeated joins or by fabricating a native ID. Use a supported harness/platform from the support section. receive is an active delivery consumer; use inbox for a read-only investigation.

When work is complete, unsubscribe and leave using the same session identity. For dependency tracking use saved plans; they do not dispatch messages or certify results. For instruction-delivery questions use behavior management.