Attention sound
Open Settings → Attention sound in TUI, web or desktop. The setting is OFF by default and persists for the signed-in controller user across clients and server restarts. Test sound plays once on this device without changing the preference.
A signal means a fresh native session observation reports an explicit question or permission request, or a new pending MCP approval needs review. Ordinary completed turns, optional Decisions advice, resource warnings and stale/process-only telemetry are silent. Native Claude, Codex and supported provider hooks use the existing lifecycle categories; unsupported observations do not invent attention.
One shared React monitor continues while a terminal is attached. It reads a small
authenticated metadata feed every five seconds, also keeping navigation counts
current when sound is disabled. Failures back off to at most one request per minute. It does not load
conversation text, account credentials, approval arguments, history or /v1/state.
The plain disabled sound feed returns immediately; the console's navigation view
counts only owned session metadata and does not scan approval arguments.
Waiting sessions in navigation
Projects shows the number of nonhidden owned sessions matching the independent session attention marker settings. Questions and permission requests are selected by default; ordinary idle and proven quota limits can be enabled separately. Shell sessions, Control Room, stale lifecycle observations and optional advice do not count. The badge disappears at zero and updates while another screen, such as Events, is open. TUI, web, desktop and the mobile navigation selector share this count. Sound does not need to be enabled. Pending MCP permission requests count once for their session and retain their separate approval count. Hiding a session excludes its marker while leaving canonical sound/push behavior unchanged.
First load and reconnect establish a quiet baseline. An unchanged attention state does not repeat, including through temporarily stale telemetry. Simultaneous transitions share one signal, with a ten-second cooldown. Suppressed signals are discarded rather than replayed later. Incomplete feeds reestablish a quiet baseline.
Local playback
Web and Tauri synthesize the short tone through Web Audio on the user's device.
The original devctrl signal is a quiet 340 ms rising sine tone with a soft attack
and release, generated from the project's recipe in attention-tone.ts and the
standalone launcher's matching PCM recipe. It uses no third-party recordings,
brand sounds or operating-system samples. A cross-runtime test verifies the
recipes match. Test and attention notifications use the same signal.
There are no downloaded sound assets, speech/model calls or server-side speakers.
Browsers can require a user gesture before audio works: the settings show LOCKED
until interaction or Test sound unlocks it. OS sleep or browser interruption can
lock it again; the next interaction retries. Muted tabs, device volume, background
throttling and sleeping devices can suppress sound.
TUI uses the existing private client launcher bridge to play that same generated
WAV on the computer running ./devctl tui or devctrl tui remote. macOS uses
afplay, Windows uses winsound.PlaySound, and Linux uses an installed paplay
or aplay. No download or additional dependency is required. This does not play
through a speaker on the remote execution host. The authenticated loopback bridge
and private local IPC accept only the fixed signal, with bounded playback and no
arbitrary file or command parameter.
Without a working client sound bridge/player, TUI sends one zero-width BEL to the
user's terminal. Its audible/visual bell may be disabled; the result explicitly
reports this fallback, which cannot reproduce the custom timbre or confirm
audibility. Redirected output, dumb terminals and real CI are unsupported.
Choose Test sound with ↑/↓ then Enter, press t, or click it in web/desktop.
Testing works while the notification preference is OFF and reports the output used.
earshot was reviewed as an optional sound design tool (MIT code; separate model licenses). devctrl does not copy its samples, depend on it, download its models or run inference to play this procedural signal.
Keep the console process open. A closed browser or desktop client cannot play this local custom tone. Existing browser push and messenger notifications are separate channels with their own settings. Public read-only session links do not read a private user's sound preference or start the monitor.
Controller API and operator MCP
GET /v1/preferences/attention-soundreads{ "enabled": false }by default.PUT /v1/preferences/attention-soundsaves only{ "enabled": true|false }for the authenticated user. The mutation is audited; another user cannot be selected.GET /v1/notifications/attentionreturns that user's preferences and at most 1,000 minimal session/approval IDs, generation, category and reliability, with an explicittruncatedflag. It never attaches terminals or changes sessions.- The same feed with
?view=navigationadds an exactprojectSessionAttentionCount, independently of sound and the 1,000-item notification limit. It contains no project names or prompt text.
The existing operator MCP controller_operations / controller_request tools
discover and call these same routes. Session-scoped agents cannot change console
preferences through their ordinary project MCP identity. An operator-requested
change does not bypass controller authentication or user ownership.