Skip to content
beebee

Let the agent wire itself up

The adapters described in Collaborate need a few files in the right places: an MCP server entry for Claude Code, lifecycle hooks, or a join call for Codex. You can write them by hand. You can also hand the job to the agent that will use them — it already has file access to the project and can verify its own work afterwards.

The prompts below are written to be pasted as-is.

Before you paste

Section titled “Before you paste”

These prompts contain no paths, hostnames, databases or credentials on purpose. The agent is told to discover what it needs and to stop and ask rather than guess. Two habits matter more than the prompt text:

  • Never paste a broker password or a database URI into a prompt. Bee reads BEE_MQTT_USERNAME and BEE_MQTT_PASSWORD from the environment, or the secret-masked mqtt.username / mqtt.password config keys. Prompts end up in transcripts; secrets should not.
  • Read the diff before you accept it. Both prompts ask the agent to show the change before writing. .mcp.json and .claude/settings.json may already contain entries that belong to other tools, and merging is not the same as overwriting.

Bee must already be initialised against your shared store and broker — see First run and the configuration section of Collaborate. Neither prompt configures the store for you, because the correct values are your team’s, not the agent’s guess.

Claude Code

Section titled “Claude Code”
Set up the Bee Collaborate channel for this project, then verify that this session has joined.


Bee's documentation is at https://bee.fusapp.com/collaborate/ — read it before you
change anything. Work in these steps and stop at the first one you cannot complete.


1. Locate the bee executable and print the absolute path you resolved.
   It must be the real binary. On Windows a `.cmd` or `.bat` shim will not work as an
   MCP command: MCP clients spawn the executable directly and the spawn fails with
   EINVAL. Prefer a stable path that survives tool updates over one containing a
   version number.


2. Check collaboration configuration and run the maintenance check:
       bee config show
       bee worker --once --json
   This runs maintenance only; it does not start or prove the receiver. Separately
   inspect the OS process or service status for the long-running bee worker and
   report whether it is running.
   If collaboration is not enabled, or no broker is configured, STOP and tell me what
   is missing. Do not invent a broker host, a space name, a database or any credential.


3. Show me the exact change you intend to make to `.mcp.json`, then apply it.
   Add a `bee-collaborate` stdio server that runs the bee executable with the
   arguments `collaborate channel`. MERGE with the existing content; do not drop
   entries that are already there. Only set BEE_HOME if this project uses a bee
   profile that is not the default one.


4. Show me the exact change you intend to make to the Claude settings file, then apply
   it. Add SessionStart and SessionEnd hooks that run the same executable with
   `collaborate channel-hook --event SessionStart` and `--event SessionEnd`. Hook
   arrays merge, so keep every hook that is already registered. If this machine uses a
   path or profile that other machines do not share, put the hooks in the local
   settings file rather than the shared one.
   On Windows do not use a `VAR=value command` prefix — it is not valid shell syntax
   there; rely on the default profile instead.


5. Never set CLAUDE_CODE_SESSION_ID yourself. The live host supplies it, and the
   channel refuses to bind to an identity it was handed rather than given.


6. Tell me the exact command to restart Claude with the Channels development opt-in
   for this server, and tell me plainly that the channel stays inactive until I do it
   and accept the prompt. Ordinary MCP registration alone is not enough.


7. After I restart, call the bee_peers tool and show me the raw result. Check that
   it returns successfully without a session-binding error. An empty peer list is
   normal: the caller is excluded. This checks binding, not message delivery. If the server fails to
   start, its real reason goes to stderr while stdout stays empty, so the client shows
   nothing but a closed connection — run the executable yourself with the same
   arguments and read stderr before you diagnose anything.


Do not commit any of these files unless I ask.

Codex

Section titled “Codex”
Set up Bee Collaborate for this Codex session, then verify that this session has joined.


Bee's documentation is at https://bee.fusapp.com/collaborate/ — read it before you
change anything. Work in these steps and stop at the first one you cannot complete.


1. Locate the bee executable and print the absolute path you resolved.


2. Check collaboration configuration and run the maintenance check:
       bee config show
       bee worker --once --json
   This runs maintenance only; it does not start or prove the receiver. Separately
   inspect the OS process or service status for the long-running bee worker and
   report whether it is running.
   If collaboration is not enabled, or no broker is configured, STOP and tell me what
   is missing. Do not invent a broker host, a space name, a database or any credential.


3. Join this actual conversation — not a new one. Use the harness `codex`, a short
   name describing what you work on here, and the real native thread id from the
   environment. Print the full JSON result:
       bee collaborate join --harness codex --name <short-name> --native-id "$CODEX_THREAD_ID" --json
   If the thread id is empty, STOP: an old transcript cannot stand in for a live
   session, and a fabricated id would register a peer nobody can reach.


4. Take `session.id` from that result and pass it explicitly on every later call as
   BEE_COLLABORATE_SESSION_ID. A separate shell invocation does not keep an exported
   variable, so set it per command. Use the same BEE_HOME profile throughout.


5. Subscribe to the topic filter I give you, or ask me for one. Do not subscribe to a
   filter you chose yourself:
       BEE_COLLABORATE_SESSION_ID='<session.id>' bee collaborate subscribe '<filter>' --json


6. Verify session registration. Print the raw output of:
       BEE_COLLABORATE_SESSION_ID='<session.id>' bee collaborate peers --json
   Check for a successful response without a binding error, using session.id from
   the join result. An empty peer list is normal: it excludes the caller. This does
   not prove message delivery. Remember what the delivery states
   mean: transport_written says the message was written to the transport, not that any
   model read it. Do not describe a transport write as a delivered message.


7. Tell me if this machine runs Windows. Ownership checks for the Codex adapter use
   lsof and writer locks on macOS and Linux, and waking an idle Codex session is not
   implemented on Windows — say so plainly instead of reporting full support.


Do not commit any files unless I ask.

After the agent reports success

Section titled “After the agent reports success”

Ask for the raw tool or command output, not a summary. A configuration file that merely exists proves nothing. A successful bound bee_peers call checks the channel binding; the caller is excluded from the list, so an empty result is normal. For Codex, retain session.id from the successful join result. For what the different delivery states are actually evidence of, see What a delivery status proves.