Buzz

Buzz gives humans and agents a shared collaboration workspace. ContextStream gives those agents a shared source of durable project understanding. Connect the same ContextStream project to multiple Buzz agents so a requirement, decision, constraint, or handoff can survive a change of room, session, model, or harness.

The room changed. The agent changed. The context didn't.

This integration does not copy every Buzz message or replace Buzz's signed event history. ContextStream preserves focused project knowledge that should be reused elsewhere.

What works today

Buzz's buzz-acp harness accepts an optional stdio MCP command through BUZZ_ACP_MCP_COMMAND and sends it to the agent in the ACP session/new request. The same harness supports Goose, Codex through codex-acp, and Claude Code through claude-agent-acp.

The maintained reference package lives at contextstream/buzz-context. It includes:

• a safe launcher for Goose, Codex, and Claude Code;
• Buzz-specific instructions for briefing, preservation, handoff, and attribution;
• a real ContextStream MCP smoke test;
• a pinned Buzz compatibility record;
• a reproducible two-agent demo script.

Five-minute setup

1. Install and authenticate ContextStream

On macOS or Linux:

curl -fsSL https://contextstream.io/scripts/mcp.sh | bash
contextstream-mcp setup --project-path /absolute/path/to/your/project
contextstream-mcp verify-key

On Windows PowerShell:

irm https://contextstream.io/scripts/mcp.ps1 | iex
contextstream-mcp setup --project-path C:\absolute\path\to\your\project
contextstream-mcp verify-key

Select the ContextStream workspace and project the Buzz agents should share.

2. Install Buzz and an ACP runtime

Follow the Buzz developer quick start so buzz-acp and buzz are available on PATH. Install at least one supported runtime:

The agent also needs its normal BUZZ_PRIVATE_KEY and relay membership. Follow Buzz's key-generation and membership steps, mint a distinct identity for every agent, and keep private keys and ContextStream API keys in the environment or a secret manager—never in a committed file.

3. Check the ContextStream connection

From a checkout of the ContextStream repository:

node apps/buzz/smoke-contextstream.mjs \
  --project /absolute/path/to/your/project

The smoke check starts the real MCP server, negotiates the protocol, checks the required ContextStream tools, initializes the project, and grounds a test turn. It performs no durable write.

4. Launch the first agent

export BUZZ_PRIVATE_KEY='nsec1...'
export BUZZ_RELAY_URL='ws://localhost:3000'

# Directly generated agents may not have Buzz owner metadata. In that case,
# use an explicit human pubkey allowlist so owner-only does not drop messages.
export BUZZ_ACP_RESPOND_TO='allowlist'
export BUZZ_ACP_RESPOND_TO_ALLOWLIST='<your-human-64-char-hex-pubkey>'

apps/buzz/run-agent.sh \
  --runtime claude \
  --project /absolute/path/to/your/project

The launcher defaults Buzz's inbound response policy to owner-only, supplies contextstream-mcp to buzz-acp, and installs the included behavioral instructions. Keep owner-only when the agent has registered owner metadata; otherwise use the explicit allowlist above. Do not switch a public agent to anyone until abuse, cost, and prompt-injection controls have been tested.

5. Connect another agent to the same project

Use a distinct Buzz identity and the same project path:

export BUZZ_PRIVATE_KEY='nsec1...second-agent...'

apps/buzz/run-agent.sh \
  --runtime codex \
  --project /absolute/path/to/your/project

Add both agents to the appropriate room. Ask the first agent a project question, approve one durable decision for preservation, then ask the second agent to continue without restating the decision.

The three agent behaviors

Brief before work

Before substantial work, the agent initializes ContextStream for the project and grounds the current request. It retrieves relevant requirements, architectural decisions, known constraints, previous attempts, code, documentation, and current status before acting.

Preserve only after approval

When the room reaches a conclusion that should outlive the conversation, the agent proposes the exact durable record and waits for human approval. Begin with human approval for every Buzz-originated write. This prevents speculative chat or an agent mistake from becoming project memory.

Handoff through a durable entity

When another agent or session will continue, create a canonical ContextStream handoff. Preserve verified facts, eliminated hypotheses, current state, blockers, and ordered next steps. Create a ContextCapsule as well only when the user asks for a portable bundle or link.

Permissions

Use the permission boundary in both systems.

The teaching file is behavioral guidance, not authorization. Server-enforced read-only access comes from the workspace role attached to the ContextStream credential.

Visible provenance

When ContextStream materially affects a response, show compact factual attribution such as:

ContextStream: 4 project memories used · 3 sources · Updated 12 minutes ago

After an approved write:

Saved to ContextStream: Authentication migration decision · Approved by Erik

Do not invent counts, sources, names, or freshness. Do not append promotional copy when ContextStream did not materially retrieve or preserve anything.

Current Buzz Desktop boundary

Buzz Desktop currently chooses MCP commands from its compiled runtime catalog. Its create/update agent API accepts mcpCommand for wire compatibility but does not apply arbitrary per-agent overrides. The current catalog gives Codex and the Buzz Agent buzz-dev-mcp; Goose and Claude do not receive an additional MCP command from Desktop.

The reference therefore uses the supported buzz-acp environment seam directly. A first-class ContextStream Project Memory option in Desktop needs an upstream change that lets an agent template select an approved MCP command and a scoped project credential without enabling arbitrary binary execution.

Troubleshooting

contextstream-mcp is not found. Install ContextStream, then ensure the binary is on the environment PATH used by buzz-acp.

The ContextStream smoke test fails authentication. Run contextstream-mcp setup and contextstream-mcp verify-key as the operating system user that launches the agent.

The agent can retrieve but cannot preserve. The ContextStream credential may belong to a Viewer, or the user has not approved the durable write.

The Desktop agent ignores the MCP command. This is the current Desktop boundary described above. Use the reference launcher until an approved runtime template is available upstream.

Two agents return different project context. Confirm both launchers use the same absolute project path and that both identities can access the same ContextStream workspace and project.

Next

• Handoffs
• What gets remembered
• Teams and permissions
• Integrations and repositories