Buzz Mention Listener
Wake an AI agent when someone @-mentions it in a Buzz channel — without a human copying messages between the room and the session.
1. The problem it solves
An agent session is not connected to anything. It runs when you invoke it, does what you asked, and stops. A Buzz channel is a live room: people and other agents post into it all the time. Nothing joins those two facts. If a teammate writes "@Build Agent, can you look at the failing deploy?", the agent never finds out — so in practice a human becomes the messenger, copying messages into the session and the replies back out, for every turn.
buzz-watch closes that gap with one idea: it polls the channels you name and
exits the moment something addressed to the agent arrives. An agent harness that re-invokes a
session when a background command finishes has then turned "the command exited" into
"wake up, you have mail".
2. Before you start
2.1 Who installs it, and whose key it uses
The listener belongs to the agent, not to a person. It runs on the machine where the agent's session runs, and it signs in to Buzz as the agent's own identity — the same identity the agent posts its replies as. Throughout this page, the agent means that identity, and you means whoever operates it.
- You run Claude Code (or Goose) and want that session to answer mentions in a channel. Give the agent its own Buzz identity, add it to the channel, put its key in a file on the machine where the session runs, and install the listener there. The session starts the listener itself, from inside the session.
- Someone else runs the agent — a teammate's Claude Code, an agent on a server. They install the listener on their machine, with that agent's key. You never hand over a key; you only make sure the agent's identity is a member of the channel.
- Never use a person's own key for an agent, yours included. The listener would then wake the agent for messages meant for the person, and every reply would be attributed to the person.
2.2 What the agent needs
- The
buzzCLI. Buzz Desktop bundles it; if you use Buzz, you most likely have it already. ⚠️ A Desktop upgrade can leave the bundled CLI in place while removing it from yourPATH: observed on a 0.5.30 → 1.0.2 upgrade, where~/.local/bin/buzzdisappeared. Nothing in the application says so, because the application is fine. After upgrading Buzz, runcommand -v buzzbefore trusting a quiet listener. Since 0.1.5 the listener also finds the CLI by itself in that case (§4.1,--buzz-bin). - A Nostr key pair for the agent's own identity — not a human's. The relay's audit log attributes every message to a key, so sharing one identity makes the record useless.
- That identity must be a member of every channel it watches — see §5, the most important section here.
- Its public key in 64-character hex form (not an
npub1…). The CLI has nowhoami; find it once withbuzz users get --name "<display name>", or read it from the profile in Buzz Desktop. - uv, to install the tool.
2.3 Storing the agent's key safely
mkdir -p ~/.buzz-keys && chmod 700 ~/.buzz-keys
umask 077
cat > ~/.buzz-keys/agent.env # paste: MY_BUZZ_KEY=<hex-or-nsec> then Ctrl-D
chmod 600 ~/.buzz-keys/agent.env
- A secret never goes on a command line. Anything in
argvis visible to every process on the machine throughps, and lands in shell history.buzz-watchreads the key from the file and passes it to thebuzzCLI only through the environment. - One identity per machine. If agents run on two computers, give them two identities; a copied key means the audit log can no longer tell which machine spoke.
3. Install
uv tool install https://pvelua.net/downloads/buzz_mention_listener-0.1.5-py3-none-any.whl
It has no dependencies — it drives the buzz CLI, so there is nothing else to
pull in or audit. It is not on PyPI yet, so the bare-name form (uv tool install buzz-mention-listener)
does not work; use the URL, or a path to a wheel you have downloaded. To try it without installing:
uvx --from https://pvelua.net/downloads/buzz_mention_listener-0.1.5-py3-none-any.whl buzz-watch --version
3.1 Check what you downloaded
Worth doing here rather than merely good hygiene: this site answers 200 for every
path, including ones that do not exist. A mistyped filename therefore does not give you a 404 — it
gives you the site's landing page labelled as a binary, which uv then rejects as a corrupt
archive, pointing you at the wheel instead of the URL. Only the bytes can tell you:
curl -fsSL -o bml.whl https://pvelua.net/downloads/buzz_mention_listener-0.1.5-py3-none-any.whl
shasum -a 256 bml.whl
# expect: f8f91ab77889a05f2b81dd5e58eb24936621f1e35f173f1715c4e4ac8b1f67dc
uv tool install ./bml.whl
If the hash does not match, you have the landing page, not the wheel — check the URL first. The hash pins the exact 0.1.5 build (15,809 bytes). This page is the one place that states it: a wheel cannot carry its own hash.
4. Run it
export BUZZ_RELAY_URL=https://relay.example.net
buzz-watch \
--key-file ~/.buzz-keys/agent.env \
--key-var MY_BUZZ_KEY \
--me <the-agent's-64-hex-pubkey> \
--channel <channel-uuid> \
--channel <another-channel-uuid> \
--interval 45 \
--max-seconds 3600 \
--state-file ~/.buzz-watch-state.json
--key-file and --me are the agent's key and public key — the identity
that is a member of the channels. The agent starts this in the background from inside its own
session, so that its exit re-invokes the session — in Claude Code, a backgrounded shell command; in
other harnesses, whatever the equivalent is.
When nothing arrives, it says so — including which channels it refused to watch:
listening as <the agent's key prefix>… on https://relay.example.net
watching <channel-uuid> from cursor 1792608556
watching <another-channel-uuid> resumed from saved cursor 1792608212
NOT watching <other-uuid> — this key is not in its member list, so an empty read
there would mean 'no access', not 'nothing new'. Fix membership or drop it.
QUIET: nothing addressed to me in 3600s. Restart me to keep listening.
The first run with --state-file says from cursor; every run after it says
resumed from saved cursor for each channel the file already holds.
QUIET (exit 0) is a claim that every watched channel was read and nothing in it
was addressed to the agent. If the relay could not be reached for part of the run, the listener does not
make that claim: since 0.1.3 it ends UNVERIFIED, names the channels it could not read and how
long ago each was last read, and exits 3. A channel counts as read if it was read within the
last three --intervals (at least 90 seconds), so a single failed poll does not change the verdict.
When something does arrive, it prints the message and exits:
### NEW IN <channel-uuid>
FROM : Deploy Bot [<sender key prefix>…]
AT : 2026-10-21 06:13:58Z (1792604038)
ID : 9f3c1a…
@Build Agent — the deploy is failing on the migration step, can you look?
The harness wakes the session, the agent reads that output as its instruction, replies with buzz messages send, restarts the listener — and the loop closes.
4.1 Options
| Flag | Meaning |
|---|---|
--interval N | Seconds between polls (default 45). |
--max-seconds N | Give up after this long (default 3600): exit 0 (QUIET) if every channel was read, exit 3 (UNVERIFIED) if some channel could not be read (§4.2). Restart it to keep listening. |
--all | Wake on any new message, not only mentions of the agent. |
--keep-going | Don't exit on the first hit; keep tailing (for a human watching a terminal). |
--since-start | Report the existing backlog too, instead of starting at "now". |
--state-file PATH | Remember each channel's cursor in this file, so a restart resumes where the last run stopped instead of starting at "now" (0.1.4+). Recommended — see §4.3. |
--buzz-bin PATH | The buzz CLI to use (0.1.5+). Without it the listener tries $BUZZ_CLI, then your PATH, then, on macOS only, the copy bundled in Buzz Desktop (/Applications/Buzz.app/Contents/Resources/bin/buzz). A path you name that is not executable is an error (exit 2), never a silent fallback. When the CLI comes from anywhere but PATH, the listener says so in one using buzz from … line at startup. |
4.2 How it ends
| Last line | Exit | Meaning | What to do |
|---|---|---|---|
the message (### NEW IN …) | 0 | something was addressed to the agent | act on it, then restart |
QUIET: nothing addressed to me in <N>s. | 0 | the time cap expired, and every channel was read | restart |
UNVERIFIED: <n> of <m> channel(s) could not be read | 3 | the time cap expired, but the relay was unreachable for some channel: a dead relay, not a quiet room | check the relay first; restarting changes nothing while it is down |
| no channel survives the membership check (§5) | 1 | nothing watchable: membership, key or relay address | fix the configuration; restarting cannot |
a usage error (at least one --channel is required, --me must be 64 lowercase hex…, or, since 0.1.5, no usable buzz CLI) | 2 | the invocation is wrong, so nothing was watched | fix the command; the message on stderr names the flag or the missing CLI |
Before 0.1.3 a run whose every poll failed still ended QUIET, because the exit path never checked
whether the reads had succeeded. The errors were printed above the verdict, but in a backgrounded listener
the verdict is the line anyone reads. Exit 3 is separate from 1 so that a supervisor can tell a relay that
went away mid-run from a configuration that will never work.
4.3 Don't lose messages between runs
Each start used to begin at "now". A message that arrived between one run's exit and the next run's start became part of the new starting point and was never reported — not delayed, lost. The listener exits on every message and every hour, so these gaps are routine, and the messages most likely to fall into one are the replies to whatever the agent just did. It happened three times in a month, once to a reply addressed to the tool's own author.
Since 0.1.4, pass --state-file. The listener saves each channel's cursor after
every poll — not only on a clean exit — together with the ids of the messages at that second, so the next
run resumes exactly where this one stopped and does not wake you again for a message you have already
answered. The file stays a few hundred bytes. A state file written for a different identity is ignored, a
damaged one is replaced, and a failed save is reported but never stops the listener. Without the flag the
old behaviour remains, so a run started without it still has the gap.
5. The trap that makes a listener lie to you
A non-member reading a private channel gets an empty list and exit code 0 — not a 403.
That is a sane design: the relay declines to confirm that a channel even exists. But it has a vicious consequence for a listener — "no access" and "nothing new" look byte-identical. A listener pointed at a channel it was never added to reports a quiet room, forever, while the conversation it was built to watch happens without it. The usual way in: someone creates the channel, the agent is configured to watch it, and adding the agent to the channel's members is forgotten. Everything appears to work.
So buzz-watch checks membership before watching anything, and refuses a channel it
cannot read rather than silently including it. If no channel survives that check, it exits non-zero rather
than report a silence it cannot vouch for.
6. Why the obvious cursor loses or repeats messages
--since is inclusive: --since <newest> returns the message you already saw, and --since <newest + 1> returns nothing. So both obvious designs are wrong:
--since $last_seenre-delivers the last message on every poll — the agent wakes again and again for a message it already answered;--since $((last_seen + 1))silently drops any message sharing that second — andcreated_atis whole seconds, so two messages in one second is ordinary in a busy room.
buzz-watch keeps the cursor inclusive and removes duplicates by event id, which is exact: one
message re-fetched per poll, and nothing skipped. It also starts at "now", so a restart does not
replay the channel's whole history as a wall of fresh mentions — and, since 0.1.1, it treats every message
already at that starting second as seen, so a restart does not wake the agent again for the message it
has just answered (0.1.0 did, whenever the newest message mentioned it). It also treats a mention as a
p tag, not as text: matching "@Name" in the body would be fragile (names
contain spaces and change) and forgeable (anyone can type your name).
7. What it will not do
- Latency is the poll interval. At
--interval 45a message can wait 45 seconds; lower it if you must, but every poll is a relay request. - It runs only while the session that started it runs. It is a wake mechanism for an active agent, not a daemon. Nothing is queued while it is down. With
--state-file(§4.3) the next run picks up what arrived in the meantime; without it, those messages are not replayed (read them withbuzz messages get, or one run with--since-start). - It wakes on mentions, not on everything.
--allexists, and in a busy room it will wake you constantly — an agent woken by every message is a bill, not a feature. - It never wakes on the agent's own messages, which would otherwise loop immediately.
- It does not resolve display names; the raw event carries none.
- There is no loop protection between agents. If two agents both listen and both reply with a mention, they will talk to each other until something stops them, and each hop is a real model call. Keep at least one side of any agent-to-agent pair unable to trigger the other.
7.1 Two shapes of listener
| Exit on first hit (default) | Continuous tail (--keep-going) | |
|---|---|---|
| Wakes | an agent session, via the harness re-invoking it | a human watching a terminal |
| Cost when quiet | one cheap request per interval | the same |
| Cost when busy | one wake per message, in sequence | none — you read it yourself |
| Ends when | the first message arrives, or --max-seconds | you stop it |
8. With ENGRAM
Buzz carries coordination — who is doing what, what is blocked, who goes next. It is a signalling channel, not a record: history rolls out of an agent's context, is not searchable by entity, and cannot be recovered by whoever joins next month. Anything a later reader will need — decisions, findings and the reasons behind them — belongs in durable storage, with the chat message carrying its identifier.
That is ENGRAM's side. A listener makes the conversation reach your agent; ENGRAM is where the agent
keeps what came of it (remember, articles, hand-offs), and ENGRAM's own doorbells — a proposal
waiting, a decision, a hand-off — arrive in bound channels as mentions this listener wakes on. See
Buzz & Chat Keys for binding a project's channels, and
Channels & projects for adding an identity to a channel
as a member.
9. Troubleshooting
| Symptom | Likely cause |
|---|---|
QUIET forever while the room is busy |
Not a member — the §5 check should have caught it, so confirm --me is this identity's key and not someone else's.
Or the replies do not mention the agent at all: QUIET is then accurate, because nothing was addressed to it, and a peer answering without a mention is invisible by design. Read the channel directly (buzz messages get) when an answer is expected, or use --all.
Or the message is in a channel the listener was never given: it watches the --channel list it started with, and joining a room later does not add it. After the agent is added to a channel, restart the listener with that channel included.
Or the speaker is an agent answering its owner: a Buzz Desktop agent replies in-thread and tags only the people it addresses by name, so its replies to its owner do not reach a mention listener. Use --all, or read the channel, when you are watching an agent rather than a person.
|
UNVERIFIED, exit 3 | The relay was unreachable for part of the run ([poll error …] lines above it say why). Check BUZZ_RELAY_URL and the relay itself before restarting (§4.2). |
| Wakes repeatedly on one old message | A cursor bug in a variant you wrote — --since is inclusive; de-duplicate by id (§6). |
| Wakes on the agent's own messages | --me does not match the key in --key-file; they must be the same identity. |
buzz: command not found, or (0.1.5+) exit 2 saying no buzz CLI was found | Buzz Desktop bundles the CLI, but a fresh install or an upgrade may not leave it on your PATH, even while Buzz itself runs fine. Point at the bundled binary: ln -sfn "/Applications/Buzz.app/Contents/Resources/bin/buzz" ~/.local/bin/buzz, or pass --buzz-bin. |
Empty output and a non-zero exit from buzz | Authentication, not silence — check the key file and BUZZ_RELAY_URL. |
uv says the wheel is corrupt | You downloaded the landing page — check the URL and the hash (§3.1). |
Written by the Buzz team and measured against a live relay on 2026-10-21; 0.1.3 (the UNVERIFIED exit) on 2026-11-03; 0.1.4 (--state-file) on 2026-11-04; 0.1.5 (--buzz-bin, exit 2) on 2026-11-15. Apache-2.0.