Notifications

Caudra can tell you when a session finishes or needs your input. This is useful when you move to another terminal while Caudra works.

Notifications are enabled by default. Caudra does not notify while it knows that its terminal has focus.

Caudra uses these messages:

• Agent turn complete or a preview of the response, up to 200 characters.
• Permission requested: <tool> for a permission prompt.
• Authentication required when authentication needs attention.
• Question requested for a question prompt.
• Plan ready when a plan is ready.
• automation <name>: <text> when an automation calls notify(), with the text cut to 200 characters. The status bar flashes it too.

Response previews and automation notices can appear in your operating system's notification history. Caudra does not include tool arguments, permission scopes, question bodies, plan content, or error details. Use bell for a message-free alert, or use off to disable notifications if that text should not reach notification history.

Configuration

Set ui.notifications in ~/.config/caudra/caudra.toml:

[ui]
notifications = "auto"

Value	Behavior
auto	Use OSC 9 in a supported terminal. Use BEL otherwise.
osc9	Always send an OSC 9 notification.
bell	Always send the terminal bell.
off	Do not send notifications.

auto supports Ghostty, iTerm2, Kitty, Warp, and WezTerm. An unknown terminal uses BEL. Your terminal settings decide whether BEL makes a sound or shows a visual alert.

Caudra also recognizes xterm-ghostty and xterm-kitty from TERM. This lets OSC 9 work when an SSH connection does not preserve TERM_PROGRAM.

tmux

tmux needs both of these settings:

set -g focus-events on
set -g allow-passthrough all

Use allow-passthrough all, not allow-passthrough on. The on value permits passthrough only while the Caudra pane is visible. tmux drops the notification after you change to another tmux window.

Add the settings to ~/.tmux.conf, then reload the file or restart tmux.

Other terminal multiplexers

Caudra wraps OSC 9 for GNU screen. GNU screen does not pass terminal focus events to Caudra, so Caudra does not suppress notifications there. A notification can appear while the GNU screen window has focus.

Caudra sends OSC 9 directly through Zellij.

Herdr

In a Herdr pane, auto sends no notifications. Caudra reports its state to Herdr, and Herdr shows its own notice when the agent finishes or waits for you, so a second one from Caudra would repeat it. The notice names the prompt that is waiting, such as Permission requested: shell. An explicit osc9 or bell setting still applies. See Worktrees for what else Caudra reports to Herdr.

Focus on Windows

This terminal focus protocol is not available on Windows. Caudra treats the terminal as unfocused so an explicit bell or osc9 setting still works.