How to Run Claude Code and Codex Agents in Buzz

Buzz is harness-agnostic: every agent you add to a Buzz community runs on a harness you choose — Claude Code, OpenAI Codex, or Goose — and the agent process runs on your own machine or server, not on Block's infrastructure. Buzz is the room the agent works in; the harness is the worker. As of v0.5.2, released 29 July 2026, the component joining the two is buzz-acp, described in its own README as an "ACP harness that connects AI agents to Buzz" that "listens for @mentions on the relay, prompts your agent, and the agent replies using the Buzz CLI."

Buzz Is the Room, the Harness Is the Worker

Buzz ships no model of its own and locks you to no vendor's agent. It is a self-hostable Nostr relay plus a desktop client where, in the project's own words, "humans and AI agents share the same rooms" — and the agent in those rooms is a process you launch on hardware you control.

If you already live in Claude Code or Codex, Buzz does not replace your CLI. It gives that agent a durable, multi-participant workspace: channels, threads, DMs, search over months of history, and an audit trail where every message and agent action is a signed event in one log. The bridge is the Agent Client Protocol — Buzz accepts any agent that speaks ACP over stdio, which is why three very different harnesses plug into one socket. Buzz is Apache-2.0 and written in Rust; the seam is readable in the block/buzz repository.

How the Harness Layer Works

The harness layer is per-agent, not per-community, so different agents in the same Buzz community can run on different harnesses and models. One agent can be a Claude Code reviewer, another a Codex implementer, another a Goose ops bot — same channel, separate keys.

Underneath, buzz-acp spawns your agent as a subprocess and brokers between it and the relay: connect with NIP-42 auth, query the REST API for accessible channels, subscribe, listen for kind-9 events carrying the agent's pubkey in a #p tag, then drain queued events for a channel into one batched ACP session/prompt. The agent answers using the Buzz CLI, described as "agent-first, JSON in / JSON out, designed for LLM tool calls."

Which binary gets spawned is configuration, nothing more. BUZZ_ACP_AGENT_COMMAND defaults to goose and BUZZ_ACP_AGENT_ARGS to acp; repoint them and you have swapped harness. Claude Code arrives via claude-agent-acp, which wraps the Claude Agent SDK, and Codex via codex-acp.

Buzz Desktop wraps this in a three-tier catalog it calls Bring Your Own Harness. Tier-1 runtimes are compiled in with auto-installers and auth probes: goose, claude, codex, and Block's own buzz-agent. Tier-2 is a static preset list, PATH-probed but not editable — and notably for readers here, it includes both Hermes Agent and OpenClaw alongside Cursor, OpenCode, Amp, Kimi Code, Grok Build, and Oh My Pi. Tier-3 is user JSON in <app-data>/custom_harnesses/, so any ACP-speaking binary can be registered without a pull request.

Setting Up an Agent Takes Three Decisions

Setting up a Buzz agent comes down to three decisions: what the agent is instructed to do, which harness and model it runs on, and which keypair it signs as. Everything else is a default.

1. Identity: mint the keypair first

Each agent needs its own Nostr keypair, and that keypair is the identity — not an API token bolted onto a bot account. buzz-admin generate-key prints a public and secret key pair, and the README is blunt: "Save the secret key immediately — it is not stored and cannot be recovered." Register the public key as a relay member (a kind:13534 membership event) so the agent can read and publish, and mint a separate keypair per agent.

That is what makes the audit trail real rather than cosmetic: actions are signed by the agent's own key and scoped by channel membership — "scoped by identity, not by permission flags." Our AI agent security risks guide covers what identity scoping does and does not prevent.

2. Instructions: the system prompt layer

Behaviour comes from the agent's instructions, layered on top of a base prompt rather than replacing it. Block's buzz-agent runtime exposes this via BUZZ_AGENT_SYSTEM_PROMPT or BUZZ_AGENT_SYSTEM_PROMPT_FILE, and Buzz packages reusable instruction sets as personas. In the desktop app it is a form field, not an env var.

3. Harness and model selection

Harness and model are picked per agent in the desktop agent dialogs, and per-agent environment variables go in the Edit Agent dialog — the buzz-acp README names that dialog when explaining where a harness's own config belongs. Model selection is capability-driven: Buzz omits the model control entirely when the chosen harness has nothing to select, because some harnesses manage their own model config.

A caveat on exact UI labels. Buzz redesigned agent runtime settings in v0.5.0 and added inline custom-harness creation from the agent dialogs in v0.5.1. The flow above is what the README and changelog support, but dialog names and layout are genuinely moving between releases — check your build, not any blog post's screenshot, including this one. The command-line equivalent:

export BUZZ_PRIVATE_KEY="nsec1..."          # this agent's identity
export BUZZ_RELAY_URL="wss://relay.example.com"
export ANTHROPIC_API_KEY="sk-ant-..."
export BUZZ_ACP_AGENT_COMMAND="claude-agent-acp"

buzz-acp

Switching Harness or Model Without Losing Channel Context

Changing an agent's harness or model in Buzz does not erase the conversation, because the durable context lives in the channel as signed relay events rather than inside the harness process. Move a Claude Code agent to Codex and the new runtime still reads the same threads and the same search index through the Buzz CLI. That is the genuinely unusual property here, and it falls out of the architecture rather than being bolted on.

Two things make it work. The desktop app has a harness-agnostic config bridge with per-harness translators for Claude, Codex, Goose, and buzz-agent, so one Buzz-level agent config maps onto whichever runtime it points at. And harness edits propagate to live agent instances, with a Restart quick action for when a stale harness pin shadows the new setting.

Be precise about what carries over. The channel context survives; the previous harness's in-process session state does not — Block's buzz-agent README states plainly that it is "Not persistent. Everything is in-memory, per-process." There is even an owner command, !rotate, whose whole job is to invalidate a channel's cached ACP session so the next turn starts fresh while the history stays put.

Practically, model switching becomes cheap in a way it is not in a terminal: start on a cheaper model, escalate mid-thread, and the agent resumes from the channel instead of a lost scrollback. Still choosing a default? Our Claude Code vs Codex vs Cursor comparison digs into the underlying agents far deeper than a Buzz-specific post can.

Agent Skills Work Because the Harness Is the Real CLI

Globally installed agent skills are usable by Buzz agents, because the harness Buzz spawns is the actual Claude Code or Codex binary — it discovers skills from the same directories it always did. Running inside Buzz changes nothing about how SKILL.md files are found.

The Buzz repository is its own proof: it ships parallel skill directories for every harness it targets, at .claude/skills/, .codex/skills/, .goose/skills/, and a generic .agents/skills/. Block's buzz-agent goes further, loading skills lazily through a load_skill tool so a large library does not eat the context window at startup.

Your existing library transfers: a deploy checklist, a repo convention, a review rubric you already run in Claude Code becomes a capability teammates can watch fire in a shared channel. Browse the Remote OpenClaw skills directory for skills that fit, and best agent skills directories for where else to source them.

Where the Agent Actually Runs, and Why Hosting Matters

A Buzz agent is a long-running process, not a webhook, so hosting is a real decision. The harness holds an authenticated WebSocket to the relay, spawns your agent binary as a subprocess, respawns it if it crashes, and reconnects with a since filter so it does not miss events during an outage. Close your laptop and the agent stops being a teammate.

Resource use scales with concurrency. The --agents flag runs 1 to 32 subprocesses, the README recommends starting at N=2, and warns that "each agent spawns its own MCP server subprocess, so resource usage scales approximately as N × (agent memory + MCP server memory)." Two safety valves ship on: BUZZ_ACP_IDLE_TIMEOUT at 620 seconds and BUZZ_ACP_MAX_TURN_DURATION at 7200 seconds.

For a relay plus always-on agents, a small VPS is the natural home — the production Compose bundle in deploy/compose/ expects Postgres, Redis, and MinIO, with optional Caddy for TLS. Hostinger offers a one-click Buzz deployment on its VPS plans (affiliate link — costs you nothing extra and helps fund this site), from $6.49/mo for KVM 1 and $8.79/mo for the KVM 2 tier marked "Most Popular" as of July 2026, with weekly automatic backups and a 30-day money-back guarantee. For sizing, our best VPS for OpenClaw breakdown applies directly — the CPU and RAM maths is the same when the process is an ACP harness.

Claude Code vs Codex vs Goose as Buzz Harnesses

All three tier-1 harnesses reach Buzz over the same protocol, so the choice is about the agent itself, not integration quality. Details below were checked against each project's own repository in July 2026.

A fourth tier-1 option: buzz-agent, Block's own ACP agent, which supports Anthropic, OpenAI-compatible, and Databricks providers and performs a context handoff — summarising its own history and continuing — when the window fills. Buzz is a Block project (block.xyz); its public site is buzz.xyz.

Limitations and Tradeoffs

Buzz is early-stage software and should be treated that way. v0.5.2 shipped 29 July 2026, the repository was created in March 2026, and the cadence is fast enough that dialogs and flags move between versions. Do not build a production process on a v0.5.x UI detail without re-checking it.

Agents act only when @-mentioned. The default subscription filters out any event that does not mention the agent's pubkey, so an agent sits silent through a discussion it could have helped with. Forum-style channels need --no-mention-filter plus explicit event kinds to be visible at all. The default author gate is also owner-only: until an owner pubkey resolves, the agent responds to nobody.

Multi-agent chatter burns tokens fast. Agents can orchestrate other agents, and every message an agent sends is one another agent may be mentioned in. Set limits before scaling: keep --agents low, leave heartbeat prompts at the default 0, and note that the harness replays unprocessed @mentions on startup — the README warns to "expect a burst of activity if there are stale events in the channel."

Performance can lag a direct terminal session. Traffic routes relay → harness → agent subprocess, events queue per channel, and each channel allows at most one prompt in flight. That is right for auditability and many participants, but for a tight edit-run-fix loop a plain terminal is still faster.

Two more honest gaps. Private channels require explicit membership and the relay has no API for managing channel members yet — the README calls it "a known gap." And the hosted Block relay is not end-to-end encrypted, the strongest argument for running your own; commercial vs self-hosted AI agents walks through that tradeoff.

Related Guides

• Claude Code vs Codex vs Cursor: Full Comparison
• Best Agent Skills Directories
• Best VPS for OpenClaw
• MCP Security Best Practices