Notifications¶
tclaude raises a desktop notification when a session transitions into a
state that needs you: by default idle, awaiting_permission,
awaiting_input, error and exited. Clicking the notification focuses the
terminal window running that session. With many sessions in flight, this is
what lets you stop watching panes.
Notifications are disabled by default. tclaude setup asks once — on its
first run only — whether to enable them; re-runs never change a choice you
have already made (even with --yes), they only add notification categories
introduced by newer versions. To change your mind later, edit
~/.tclaude/data/config.json or use the dashboard's Config tab.
What setup configures¶
Along with its other work (see the setup overview), setup
installs the harness hooks that make status transitions visible, registers
the tclaude:// protocol handler on WSL so notifications are clickable, and
offers the first-run notification enable prompt. On macOS it offers to
install terminal-notifier via Homebrew. tclaude setup --check reports
the current state; --force re-registers the protocol handler.
Configuration¶
The notifications block in ~/.tclaude/data/config.json:
{
"notifications": {
"enabled": true,
"transitions": [
{"from": "*", "to": "idle"},
{"from": "*", "to": "awaiting_permission"},
{"from": "*", "to": "awaiting_input"},
{"from": "*", "to": "error"},
{"from": "*", "to": "exited"}
],
"cooldown_seconds": 5
}
}
transitions—{from, to}rules with*wildcards; the defaults above apply when the list is omitted.known_types— bookkeeping fortclaude setup: the per-type categories this block has already been offered. Setup only adds a category that is new to your config; one you switched off stays off. Written automatically; you never need to edit it.cooldown_seconds— per-session rate limit (default 5) so a flapping state does not spam you.human_messages— also notify when an agent sendstclaude agent notify-human(default true when enabled; these banners are exempt from the cooldown). See Agents and groups.notification_command— an argv array that replaces the platform mechanism entirely; tclaude writes{"title", "body", "sessionID"}as JSON to its stdin and gives it 5 seconds.delivery—os(default),browser, orboth. Browser delivery raises banners in an open dashboard tab via the Web Notification API instead of the daemon host's desktop — useful when you are remote. It needs an open tab, granted browser permission, and a secure context; queued banners expire after 10 minutes, and clicking one focuses the dashboard rather than a tmux window.
Presented PRs¶
tclaude agent present-pr always puts the PR on the agent's dashboard row.
It can optionally raise a notification too — the presenting agent, the PR
URL, and (when they fit) the --summary and the agent's group — so a review
request reaches you without watching the dashboard:
Off by default, and the notifications.enabled master switch still applies:
both must be on for it to fire. It then goes wherever delivery sends every
other notification — the desktop, a dashboard tab, or both — so under
"delivery": "browser" it is a dashboard banner rather than a desktop one.
The per-agent and per-group filters apply as well, so a muted agent's PR
still appears on the dashboard row, it just raises nothing. Only presenting
a PR notifies — --handled retires one silently. The Config tab has a
checkbox for this under Notifications → Presented PRs, and so does the
header bell's popover ("Presents a pull request").
The PR URL is the part that has to survive: a banner body is capped, and when the whole message does not fit, the summary and group are dropped and a long agent name is trimmed before the URL is touched.
An idle notification means the harness finished and no tracked subagent,
background shell, or monitor is still working — tclaude holds the session at
an internal main_agent_idle state until those settle, so you are not
pinged while a subagent is still running.
Harness labeling caveat
Notification titles are <Harness>: <Status>: Claude: …, Codex: …,
OpenCode: …, Copilot: …, Gemini: …, pi: … or Shell: …. Agent
notify-human messages, presented PRs and access requests say tclaude: ….
The task runner and rate-limit warnings always say Claude: …, whichever
harness is involved.
Click-to-focus per platform¶
| Platform | Notifier | Clickable | Focus method |
|---|---|---|---|
| Linux | D-Bus | Yes | xdotool or kdotool |
| macOS | terminal-notifier (or osascript) |
Yes | iTerm2 / Terminal.app AppleScript |
| WSL | PowerShell toast | Yes | Windows Terminal, via tclaude:// handler |
| Windows (native) | Not implemented | — | — |
Linux¶
Notifications go through D-Bus; window focus on click needs xdotool
(sudo apt install xdotool), or kdotool on KDE Plasma Wayland. Without either, notifications still appear but are
not clickable.
macOS¶
Clickable notifications need terminal-notifier (brew install
terminal-notifier; setup offers this when Homebrew is available). Without
it, tclaude falls back to osascript notifications.
WSL¶
WSL uses Windows toast notifications via PowerShell, and clicking one
focuses the Windows Terminal window through the tclaude:// protocol
handler that tclaude setup registers. If the target session lives in a
background tab, clicking detaches that tab and opens a new Windows Terminal
window with the session attached.
If clicking does nothing, run tclaude setup --check to verify the handler
and tclaude setup --force to re-register it. If notifications do not
appear at all, verify PowerShell is reachable
(/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe) and that
Windows notification settings allow toasts.
Troubleshooting¶
tclaude setup --check— hooks and protocol handler in place?~/.tclaude/data/config.jsonhas"enabled": true?- Does the transition match your rules? The defaults do not fire on
*→working, and rapid changes withincooldown_secondsare dropped.