Documentation
¶
Overview ¶
ABOUTME: terminal-bell delivery on Unix-likes — write BEL to /dev/tty, with a ABOUTME: tmux pane-tty fallback for hook subprocesses that lack a controlling tty.
ABOUTME: Linux-specific notification handling with click-to-focus support. ABOUTME: Uses background daemon for persistent D-Bus connection when click-to-focus is enabled.
Index ¶
- func EnsureClaudeNotificationsApp() error
- func FocusAppWindow(bundleID, cwd string) error
- func FocusAppWindowWithOptions(bundleID, cwd string, opts FocusWindowOptions) error
- func GetKittyWindowTarget() (windowID, listenOn string, err error)
- func GetTerminalBundleID(configOverride string) string
- func GetTerminalNotifierPath() (string, error)
- func GetTmuxPaneTarget() (string, error)
- func GetWezTermPaneTarget() (paneID, socketPath string, err error)
- func GetZellijTabTarget() (tabName, sessionName string, err error)
- func IsDaemonAvailable() bool
- func IsKitty() bool
- func IsTerminalFocused(sessionID, cwd string) bool
- func IsTerminalNotifierAvailable() bool
- func IsTmux() bool
- func IsTmuxControlMode() bool
- func IsWezTerm() bool
- func IsZellij() bool
- func MaybeCaptureGhosttyTerminalID(configOverride, sessionID, cwd string)
- func SendQuickNotification(title, message, executeCmd string) error
- func StartDaemon() bool
- func StopDaemon() error
- type FocusWindowOptions
- type NotificationPermissionDeniedError
- type Notifier
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EnsureClaudeNotificationsApp ¶
func EnsureClaudeNotificationsApp() error
EnsureClaudeNotificationsApp is a no-op on Linux.
func FocusAppWindow ¶
FocusAppWindow is not supported on non-darwin platforms.
func FocusAppWindowWithOptions ¶
func FocusAppWindowWithOptions(bundleID, cwd string, opts FocusWindowOptions) error
FocusAppWindowWithOptions is not supported on non-darwin platforms.
func GetKittyWindowTarget ¶
GetKittyWindowTarget returns the window ID and listen socket path from environment variables.
func GetTerminalBundleID ¶
GetTerminalBundleID returns empty string on Linux as terminal bundle IDs are a macOS-specific concept.
func GetTerminalNotifierPath ¶
GetTerminalNotifierPath returns an error on Linux as terminal-notifier is macOS-only.
func GetTmuxPaneTarget ¶
GetTmuxPaneTarget returns the tmux pane ID (e.g. "%42") of the pane where Claude Code is running, for use with tmux select-pane / select-window commands.
Prefers $TMUX_PANE (set by tmux per-pane at creation, always points to the process's own pane) over "tmux display-message" (which returns the currently active pane and may be wrong if the user switched tabs).
func GetWezTermPaneTarget ¶
GetWezTermPaneTarget returns the pane ID and unix socket path from environment variables. No external commands needed — the pane ID is already available in $WEZTERM_PANE.
func GetZellijTabTarget ¶
GetZellijTabTarget returns the active tab name and session name for the current zellij session.
func IsDaemonAvailable ¶
func IsDaemonAvailable() bool
IsDaemonAvailable checks if the notification daemon is available and running. Exported for testing and status checks.
func IsKitty ¶
func IsKitty() bool
IsKitty returns true if the current process is running inside Kitty with remote control enabled. Checks both $KITTY_WINDOW_ID (always set in Kitty) and $KITTY_LISTEN_ON (only set when remote control is configured).
func IsTerminalFocused ¶
IsTerminalFocused reports whether the terminal window running Claude Code currently has operating-system focus.
It is deliberately conservative: it returns true ONLY when it can positively confirm that the focused terminal belongs to this session. sessionID and cwd let platform implementations match exact tabs/windows when available. On any uncertainty - an OS API error, an unsupported platform or session (e.g. a Wayland compositor with no generic active-window query), or a terminal it cannot identify - it returns false so the caller still delivers the notification.
This bias matters: a wrong "focused" result silently swallows a notification the user is waiting for, whereas a wrong "unfocused" result merely shows one extra banner. The failure mode is therefore always an extra notification, never a missing one.
func IsTerminalNotifierAvailable ¶
func IsTerminalNotifierAvailable() bool
IsTerminalNotifierAvailable returns false on Linux.
func IsTmux ¶
func IsTmux() bool
IsTmux returns true if the current process is running inside a tmux session.
func IsTmuxControlMode ¶
func IsTmuxControlMode() bool
IsTmuxControlMode returns true if any tmux client attached to the current server is running in control mode (-CC), typically used by iTerm2. In control mode, standard tmux select-window doesn't cause iTerm2 to switch tabs; the iTerm2 Python API must be used instead.
Uses list-clients (not display-message) because display-message evaluates #{client_control_mode} for the temporary command-line client we spawn, which is never in control mode. list-clients enumerates all persistent (attached) clients, so we can check if ANY is in control mode.
func IsWezTerm ¶
func IsWezTerm() bool
IsWezTerm returns true if the current process is running inside WezTerm.
func IsZellij ¶
func IsZellij() bool
IsZellij returns true if the current process is running inside a zellij session.
func MaybeCaptureGhosttyTerminalID ¶
func MaybeCaptureGhosttyTerminalID(configOverride, sessionID, cwd string)
func SendQuickNotification ¶
SendQuickNotification sends a one-off notification without requiring a Notifier instance. executeCmd is the shell command run when the user clicks the notification (may be empty).
func StartDaemon ¶
func StartDaemon() bool
StartDaemon starts the notification daemon on-demand. Returns true if daemon started successfully or was already running.
Types ¶
type FocusWindowOptions ¶
type FocusWindowOptions struct {
GhosttyTerminalID string
}
type NotificationPermissionDeniedError ¶
type NotificationPermissionDeniedError struct {
Details string
}
NotificationPermissionDeniedError indicates macOS rejected the native ClaudeNotifier path because notification permission is denied for the app.
func (*NotificationPermissionDeniedError) Error ¶
func (e *NotificationPermissionDeniedError) Error() string
type Notifier ¶
type Notifier struct {
// contains filtered or unexported fields
}
Notifier sends desktop notifications
func (*Notifier) SendDesktop ¶
SendDesktop sends a desktop notification. On macOS, it always prefers ClaudeNotifier/terminal-notifier to avoid Script Editor attribution and optionally enables click-to-focus. On Linux with clickToFocus enabled, it uses the background daemon. cwd is the working directory of the project; used for window-specific focus. May be empty.
Source Files