Notch integration

The state channel

A client thread connects to the notch agent's socket, sends a hello, and pushes coalesced mux_snapshot frames — the full pane tree across all spaces — whenever state changes, roughly once a second under load. The wire format is a 4-byte length prefix plus JSON, mirrored exactly on both sides (raven-proto is a shared crate). If no notch is listening the thread backs off and retries; the terminal runs exactly the same without it.

What streams up

• Working directory and title per pane
• Foreground process — including the detected agent and its idle, working, or waiting-for-you state
• Unseen-output flags, OSC 9;4 progress percentages, and bell events
• Hook-reported metadata (custom statuses, display names) from report-agent

What comes back down

• focus_pane — the notch focuses the exact pane behind a notification; ⇧⌘J steps through the queue
• launch_window— the notch's + button spawns a new terminal session
• term_command — run a command in a pane, e.g. from a planning flow
• ping/request_snapshot — health checks and resyncs

Every command raises and activates the window, so answering a notification always lands your cursor in the right session. The round-trip is covered by tests on both ends.

Shared state, one source of truth

Beyond the socket, the terminal and the notch deliberately share on-disk state under ~/.raven/: the theme file, the settings the overlay mirrors, and the raven-usage accounting both usage meters render from. Change something in either surface and the other follows.