Notifications & status
Ghostex tracks agent activity across sessions and surfaces it through sidebar badges, optional floating counters, menu bar indicators, completion sounds, and macOS attention notifications.
Session activity states
Each session card projects one of three activity states:
| Option | What it does |
|---|---|
working | Agent is actively running. Shown with working indicators in sidebar, floating overlay, and menu bar. |
idle | Session is open but not currently working or waiting for input. |
attention | Agent needs your input. Triggers attention styling and optional macOS notifications. |
Agent hooks installed from first-launch or Settings → Integrations feed these states for supported CLIs (Claude, Codex, OpenCode, Pi, Gemini, Copilot, and others).
Completion sounds
| Option | What it does |
|---|---|
completionBellEnabled | Master toggle for completion sounds. Enabled by default. |
completionSound | Sound played when agent work completes. Default: arcade. Options include ping, glass, shamisen, success-chime, flawless-victory, and more. |
actionCompletionSound | Sound for action-completion feedback (sidebar command buttons). Default: shamisen. |
Settings → Sounds lets you preview sounds and test the completion flow. Changing the completion sound in Settings plays a preview immediately.
macOS attention notifications
| Option | What it does |
|---|---|
showMacOSAttentionNotifications | Show macOS banners when a background session transitions to Needs Attention. Enabled by default on new installs. |
When enabled, Ghostex requests macOS notification permission on first use. Settings provides a test action for the current completion alert flow and a shortcut to open macOS Notification Settings.
Attention notifications are rate-limited per session and globally to avoid spamming when many sessions change state at once.
Sidebar status chrome
- Session cards show agent identity, activity color, tags, and optional Last Active timestamps.
- Project headers can show git diff stats (+added / -removed lines).
- Recommended preset keeps agent icons hover-only while showing detailed status chrome.
- Use acknowledge-session-attention from the CLI to mark a session's attention event as seen.
First-launch defaults
- showMacOSAttentionNotifications: true
- completionBellEnabled: true
- completionSound: arcade
- Agent hooks: required for automatic In Progress / Needs Attention detection and first-prompt titles.