Search BrigadeStack

Search BrigadeStack pages and docs.

BrigadeStack
Menu
Docs menu

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.

Stop event on stdin
{  "hook_event_name": "Stop",  "session_id": "abc123",  "cwd": "/srv/app"}
agent-notify --hook claude-code-stop
POST to your Discord webhook
{"embeds": [{  "title": "Claude Code",  "description": "Session ended",  "color": 3447003,  "footer": {"text": "claude-code"}}]}
POST to your Signal CLI host
{  "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 status reports whether agent-notify is installed and configured, and how many channels it selects. It never sends.

  • Hooks call it

    Claude Code Stop and Notification hooks and the Codex notify line run agent-notify each time the agent stops or needs you.

  • Events leave a receipt

    The event record command writes a JSON receipt in the repo's .brigade folder, 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
Result 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"...
Result 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
Result 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
Result 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 to format, from the captured payloads
LevelSignal and Telegram prefixDiscord 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, --skip and 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-notify or custom JSON.
init
Write a starter config to ~/.config/agent-notify/config.toml.
doctor
Check config and channel env without sending. --json for scripts.
status
Print the config path, profile and selected channels. --json for scripts.
hooks print <agent>
Print the hook snippet for claude-code or codex.
version
Print version, commit, build date and platform. --json for scripts.

brigadestack notifications

status
Show whether agent-notify is 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 --send to call agent-notify.

Event types: ci-green, ci-failed, handoff-waiting, handoff-ingested, release-ready, operator-alert.