Documentation
¶
Overview ¶
Package notification provides desktop notification support for the UI.
This package supports multiple notification backends:
- NativeBackend: Uses the native OS notification system (macOS, Windows, Linux)
- OSCBackend: Uses OSC escape sequences with automatic protocol detection. Prefers OSC 99 (modern standard with rich notifications) if supported, falling back to OSC 777 (urxvt extension, widely supported). Used for SSH sessions.
- BellBackend: Triggers the terminal bell character (\x07), causing an audible beep or visual flash. Works in virtually all terminals but provides no message text.
- NoopBackend: A no-op backend that silently discards notifications. Used when notifications are disabled or no suitable backend is available.
Backend selection is based on terminal capabilities, environment, and user config:
- Users can explicitly set notification_style in seshat.json (auto/native/osc/bell/disabled)
- Auto mode: SSH sessions use OSC backend (auto-detects OSC 99 vs 777)
- Auto mode: Local sessions use native OS notifications
- If focus events are not supported in local sessions, notifications are disabled (NoopBackend)
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Icon []byte
Functions ¶
func DetectOSC99Support ¶
DetectOSC99Support parses an OSC response sequence and returns true if it indicates OSC 99 notification support. This function should be called from the capabilities detection layer to determine terminal support.
func OSC99QuerySequence ¶
func OSC99QuerySequence() string
OSC99QuerySequence returns the OSC 99 query sequence used to detect terminal support. This should be sent during capability detection.
Types ¶
type Backend ¶
type Backend interface {
Send(n Notification) tea.Cmd
}
Backend defines the interface for sending desktop notifications. Implementations return a tea.Cmd that performs the notification, allowing each backend to choose between synchronous (native OS) and asynchronous (terminal escape sequences) delivery. Policy decisions (config checks, focus state) are handled by the caller.
type BellBackend ¶
type BellBackend struct{}
BellBackend sends notifications by triggering the terminal bell. This is the most basic notification mechanism and works in virtually all terminals, but provides no visual message — just an audible or visual alert depending on terminal configuration.
func NewBellBackend ¶
func NewBellBackend() *BellBackend
NewBellBackend creates a new bell notification backend.
func (*BellBackend) Send ¶
func (b *BellBackend) Send(n Notification) tea.Cmd
Send returns a tea.Cmd that triggers the terminal bell character (\x07). The terminal will emit an audible beep or visual flash based on user configuration. No message text is displayed.
type NativeBackend ¶
type NativeBackend struct {
// contains filtered or unexported fields
}
NativeBackend sends desktop notifications using the native OS notification system via beeep.
func NewNativeBackend ¶
func NewNativeBackend(icon []byte) *NativeBackend
NewNativeBackend creates a new native notification backend.
func (*NativeBackend) ResetNotifyFunc ¶
func (b *NativeBackend) ResetNotifyFunc()
ResetNotifyFunc resets the notification function to the default.
func (*NativeBackend) Send ¶
func (b *NativeBackend) Send(n Notification) tea.Cmd
Send returns a command that sends a desktop notification using the native OS notification system.
func (*NativeBackend) SetNotifyFunc ¶
func (b *NativeBackend) SetNotifyFunc(fn func(title, message string, icon any) error)
SetNotifyFunc allows replacing the notification function for testing.
type NoopBackend ¶
type NoopBackend struct{}
NoopBackend is a no-op notification backend that does nothing. This is the default backend used when notifications are not supported.
func (NoopBackend) Send ¶
func (NoopBackend) Send(_ Notification) tea.Cmd
Send does nothing and returns nil.
type Notification ¶
Notification represents a desktop notification request.
type OSCBackend ¶
type OSCBackend struct {
// contains filtered or unexported fields
}
OSCBackend sends desktop notifications using OSC escape sequences. It automatically selects the best available protocol: OSC 99 (modern standard) if supported, falling back to OSC 777 (urxvt extension) otherwise.
func NewOSCBackend ¶
func NewOSCBackend(icon []byte, supports99 bool) *OSCBackend
NewOSCBackend creates a new OSC notification backend with automatic protocol detection. If supports99 is true, it uses OSC 99; otherwise it falls back to OSC 777.
func (*OSCBackend) Send ¶
func (b *OSCBackend) Send(n Notification) tea.Cmd
Send returns a tea.Cmd that writes OSC escape sequences to the terminal. Uses OSC 99 if supported, otherwise OSC 777.
Source Files