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".

A timer wakes you on a schedule. This wakes you on an event. A schedule either wastes turns on an empty room or adds latency to a busy one.

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.

2.2 What the agent needs

  1. The buzz CLI. 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 your PATH: observed on a 0.5.30 → 1.0.2 upgrade, where ~/.local/bin/buzz disappeared. Nothing in the application says so, because the application is fine. After upgrading Buzz, run command -v buzz before trusting a quiet listener. Since 0.1.5 the listener also finds the CLI by itself in that case (§4.1, --buzz-bin).
  2. 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.
  3. That identity must be a member of every channel it watches — see §5, the most important section here.
  4. Its public key in 64-character hex form (not an npub1…). The CLI has no whoami; find it once with buzz users get --name "<display name>", or read it from the profile in Buzz Desktop.
  5. 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

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

FlagMeaning
--interval NSeconds between polls (default 45).
--max-seconds NGive 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.
--allWake on any new message, not only mentions of the agent.
--keep-goingDon't exit on the first hit; keep tailing (for a human watching a terminal).
--since-startReport the existing backlog too, instead of starting at "now".
--state-file PATHRemember 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 PATHThe 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 lineExitMeaningWhat to do
the message (### NEW IN …)0something was addressed to the agentact on it, then restart
QUIET: nothing addressed to me in <N>s.0the time cap expired, and every channel was readrestart
UNVERIFIED: <n> of <m> channel(s) could not be read3the time cap expired, but the relay was unreachable for some channel: a dead relay, not a quiet roomcheck the relay first; restarting changes nothing while it is down
no channel survives the membership check (§5)1nothing watchable: membership, key or relay addressfix 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)2the invocation is wrong, so nothing was watchedfix 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.

The general lesson: before concluding anything from an empty result, confirm that a non-empty result was possible. An empty read is evidence about your access at least as often as it is evidence about the world.

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:

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

7.1 Two shapes of listener

Exit on first hit (default)Continuous tail (--keep-going)
Wakesan agent session, via the harness re-invoking ita human watching a terminal
Cost when quietone cheap request per intervalthe same
Cost when busyone wake per message, in sequencenone — you read it yourself
Ends whenthe first message arrives, or --max-secondsyou 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

SymptomLikely 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 3The 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 messageA 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 foundBuzz 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 buzzAuthentication, not silence — check the key file and BUZZ_RELAY_URL.
uv says the wheel is corruptYou 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.