Docs / Built-in tools
Get a ping when the agent stops, on channels you own.
Inside BrigadeStack, one Go binary sends agent events to your Discord, Telegram or Signal. Nothing else leaves the machine.
{ "hook_event_name": "Stop", "session_id": "abc123", "cwd": "/srv/app"} {"embeds": [{ "title": "Claude Code", "description": "Session ended", "color": 3447003, "footer": {"text": "claude-code"}}]} { "message": "ℹ️ Claude Code\nSession ended", "number": "+15550100", "recipients": ["+15550101"]} session_id and cwd stay on your machine unless you set include_session_id or include_cwd under [claude_code_stop].
Runs on its own.
Agent hooks and BrigadeStack events call it. BrigadeStack checks the wiring without sending.
-
BrigadeStack checks the wiring
brigadestack notifications statusreports whetheragent-notifyis installed and configured, and how many channels it selects. It never sends. -
Hooks call it
Claude Code Stop and Notification hooks and the Codex
notifyline runagent-notifyeach time the agent stops or needs you. -
Events leave a receipt
The
event recordcommand writes a JSON receipt in the repo's.brigadefolder, then sends only if you pass--send. -
One channel down, the rest deliver
Channels send concurrently and best effort. A failed channel prints its provider, stage and cause, without the URL or token, and the run exits 3 so a script can tell.
Still manual: you create the webhook, bot or Signal host, put its secrets in env vars, and paste the hook snippets into your agent config. BrigadeStack never writes hook config. brigadestack notifications sits in the extras surface, so run brigadestack extras on once. There is no retry queue, so a dropped message stays dropped.
Check it before you trust it.
Four things to try first. Each one is a real command with its real output.
Doctor
“Is it wired right?”
doctor reads the config and checks each channel's env vars without sending anything. Any FAIL exits 2.
agent-notify initwrote config to ~/.config/agent-notify/config.tomlagent-notify doctor[OK ] config: loaded[OK ] claude_code_stop.privacy: Stop-hook notifications omit cwd and session_id[OK ] routing: 2 channel(s) selected[FAIL] channel:discord-main: webhook env missing or empty[WARN] channel:signal-personal: inactive channel: url/from/to env missing or empty[FAIL] channel:telegram-personal: token/chat env missing or empty exit 2: two selected channels have no env yet Hook snippets
“What do I paste into my agent?”
setup plan prints a config template and both hook snippets for the profile you name. It writes nothing.
brigadestack notifications setup plannotifications setup plan...Codex ~/.codex/config.toml:notify = ["agent-notify", "--hook", "codex-notify", "--profile", "operator"]Claude Code ~/.claude/settings.json:..."command": "agent-notify --hook claude-code-stop --profile operator"..."command": "agent-notify --hook claude-code-notification --profile operator"... 1 config template, 2 hook snippets, 0 files written CI event
“Can CI tell me when main breaks?”
event record writes the receipt first, then sends because --send is set. Here ops is a profile that routes to Discord and Signal.
brigadestack notifications event record --type ci-failed --title "CI failed" --message "test_retry failed on main" --level error --source ci --profile ops --sendnotifications event recordevent_id: 2026-11-18T172050+0000-ci-failedevent_type: ci-failedreceipt: .brigade/notifications/events/2026-11-18T172050+0000-ci-failed.jsonsent: Truesend_exit_code: 0 receipt written, sent to 2 channels Channel down
“What if Discord is down?”
The Discord URL pointed at a closed port. Signal still got the message. The error names the provider and cause, never the URL.
agent-notify --to discord-main,signal-personal "deploy done"[agent-notify] FAIL channel=discord-main type=discord error=provider=discord stage=send cause=connectionecho $?3 Signal delivered, Discord failed, exit 3 Each channel, its own format.
The ci-failed event from the walkthrough, as each channel received it.
Discord
Set DISCORD_WEBHOOK_URL to a channel webhook.
{"embeds": [{ "title": "CI failed", "description": "test_retry failed on main", "color": 15158332, "footer": {"text": "ci"}, "fields": [{"name": "tags", "value": "ci-failed", "inline": true}]}]} Signal
Set SIGNAL_CLI_URL, SIGNAL_FROM and SIGNAL_TO for your own Signal CLI host.
{ "message": "🚨 CI failed\ntest_retry failed on main\n[ci-failed]", "number": "+15550100", "recipients": ["+15550101"]} | Level | Signal and Telegram prefix | Discord embed color |
|---|---|---|
info | ℹ️ | 3447003 |
success | ✅ | 3066993 |
warning | ⚠️ | 15844367 |
error | 🚨 | 15158332 |
Telegram (TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID) gets the same emoji prefix with a bold title in Markdown V2. It is not shown because its API host is fixed in the binary, so this capture could not intercept it.
Codex messages carry the turn's model as the title, such as OpenAI · gpt-6.2-sol, and Signal and Telegram mark them with ◉ in place of the info emoji.
Private by default.
The binary sends to the channels you configured, and to nothing else.
No telemetry
No telemetry endpoints and no update checks. privacy_test.go records every outbound request and fails on any URL that is not a configured channel.
No state
No state file, log file or cache. Each run reads the config and env, sends, and exits.
Secrets by name
The config holds env-var names such as TELEGRAM_BOT_TOKEN, never the values. Send errors drop request URLs and tokens before they print.
Stop messages skip the path
Claude Code Stop messages leave out cwd and session_id unless you opt in under [claude_code_stop], and doctor reports which way it is set.
Where it fits.
It delivers a message. Something else decides when.
- A curl in your hook
- Fine for one channel. Past that you rebuild profiles, per-channel formatting,
--skipand a doctor. - Hosted push services
- They relay your message through their server and usually an account. agent-notify posts straight to your webhook, your bot or your Signal host.
- Apprise
- Apprise reaches far more services. agent-notify keeps to three, ships as one binary, and has adapters for agent hooks. If you need dozens of targets, use Apprise.
- An alerting system
- It does not poll, schedule or evaluate conditions, and it has no retry queue or templates. A hook, CI or BrigadeStack decides when, and agent-notify sends.
Command reference.
agent-notify
agent-notify "..."- Send a message. Same as
send "...". --to / --profile / --skip- Pick channels by name or profile, or drop one from the list for this run.
--hook <adapter>- Read an agent event:
claude-code-stop,claude-code-notification,codex-notifyorcustomJSON. init- Write a starter config to
~/.config/agent-notify/config.toml. doctor- Check config and channel env without sending.
--jsonfor scripts. status- Print the config path, profile and selected channels.
--jsonfor scripts. hooks print <agent>- Print the hook snippet for
claude-codeorcodex. version- Print version, commit, build date and platform.
--jsonfor scripts.
brigadestack notifications
status- Show whether
agent-notifyis installed and configured, and how many channels it selects. setup plan- Print the config template and hook snippets for a profile. Writes nothing.
event plan- Show the event, its receipt path and the command it would run. Writes nothing.
event record- Write the event receipt. Add
--sendto callagent-notify.
Event types: ci-green, ci-failed, handoff-waiting, handoff-ingested, release-ready, operator-alert.