Notifications

Overview#

Agentastic keeps a durable inbox of agent and terminal events that need your attention. An unread item can appear as:

• an urgency-colored ring around the owning terminal pane;
• a status dot on its terminal or Agent Chat tab;
• an in-app banner and, while Agentastic is inactive, a macOS notification;
• an entry in the notification-history panel.

Press Shift-Command-U or choose Navigate > Next Agent Needing Attention to reveal the next unread agent terminal. Landing on an item marks it as seen, so repeating the command drains the queue instead of cycling the same items.

Opening or restoring a workspace does not silently clear attention.

Clearing attention#

Attention clears from the terminal itself — you never have to open the notification panel to dismiss a ring.

How much it takes depends on what the item is:

Item	Cleared by
An agent finished (blue)	Looking at the pane
An agent is blocked on you (orange)	Engaging with the pane
An agent failed (red)	Engaging with the pane

Looking at the pane means the terminal is the visible one in a pane and its window is the key window, for about a second. Nothing that is still waiting on you can be silenced this way — a blocked or failed agent is the only pointer back to a stalled session, so it survives a glance.

Engaging with the pane is any of:

• typing, clicking, or scrolling in the terminal;
• sending a message from an Agent Chat pane;
• clicking the ✕ that appears on the ring when you hover it;
• Mark as Seen in a terminal tab's context menu;
• Mark All as Seen in a worktree's context menu in the navigator, which covers every terminal under that worktree at once;
• opening the item from the notification panel or via Shift-Command-U.

Rings are drawn only around the terminal that is actually in front of you, so clearing one never hides attention still owned by a background tab — that stays visible as a status dot on the tab.

An agent or script can acknowledge its own terminal over the local socket:

level accepts glanced or engaged and defaults to engaged.

How events enter Agentastic#

Agentastic uses structured signals rather than scraping arbitrary text from the terminal screen.

Provider lifecycle hooks#

Integrated agent terminals automatically receive Agentastic's compatible provider hooks. For example, Claude hook events such as PermissionRequest, Notification, Stop, and SessionEnd are reduced to lifecycle and session identity fields, then sent over the terminal's local Unix socket. Agent prompt and conversation content are not copied into the notification inbox.

Provider lifecycle states are mapped to terminal-scoped states such as running, waiting for input, finished, and failed. Newer states resolve older attention for the same terminal while retaining it as read history.

You do not need to edit ~/.claude/settings.json to enable the built-in integration.

Explicit terminal notifications#

An agent or script can create a routed notification from its Agentastic terminal:

Clear that terminal's current notification with:

These commands use JSON-RPC over Agentastic's local Unix socket. The server does not report success until the corresponding inbox mutation has reached durable storage.

Terminal bell fallback#

Tools without a provider hook can still emit the standard terminal bell:

This is an explicit terminal control signal, not a match against visible output. Support depends on the selected terminal backend.

Legacy waiting-file integration#

Workspace tooling can continue to expose aggregate waiting state through:

Clear it with:

The file-based indicator is a compatibility path. Structured hooks and dev notify carry the stable terminal route needed by pane rings and next-attention navigation.

Durable inbox behavior#

Inbox records include read state, timestamp, urgency, source, and stable terminal/worktree routing data. Writes are:

• serialized as typed insert, read, and delete mutations;
• protected by an inter-process lock so simultaneous Agentastic processes do not overwrite each other's records;
• atomically replaced and synced before authoritative hook RPCs are acknowledged;
• bounded by both record count and encoded file size, evicting read history before unresolved attention.

Malformed snapshots are preserved for recovery. Files written by a newer, unsupported schema version are never overwritten by an older build.

Each terminal route also records its owning app-process identity. If another Agentastic process presents that history item while the owner is still running, focus is relayed to the exact owner over its validated Unix socket. A route is adopted after relaunch only when the exact terminal ID has been restored locally; a matching worktree alone is not sufficient. Processes synchronize read and removal state for items they already present without importing newly created foreign panes into their live UI.

Notification controls#

The notification panel provides:

• Next agent needing attention
• Mark all as read
• Clear read notifications

These are a backstop rather than the primary path — see Clearing attention for the in-pane controls.

The Agent Notifications preference disables lifecycle inbox entries as well as banners, sounds, badges, and pane rings. Events for a terminal that is already focused are retained as read history only while lifecycle notifications are enabled.

Troubleshooting#

No pane ring appears#

1. Confirm Settings > Notifications > Agent Notifications is enabled.
2. Confirm the event came from an integrated terminal with a stable terminal ID.
3. For custom tools, test with dev notify from that terminal.
4. Restart an older agent session after updating Agentastic so it receives the current provider-hook environment.

A ring will not clear#

1. Orange and red rings do not clear from a glance by design. Type in the terminal, or use the ring's ✕ or the tab's Mark as Seen.
2. Confirm the Agentastic window is the key window; a glance is only counted while the window is active.
3. A ring on a background tab is expected — only the visible terminal is glanced. Use Mark All as Seen on the worktree to cover every tab.

macOS banners do not appear#

1. Check System Settings > Notifications > Agentastic.
2. Agentastic suppresses duplicate external delivery while its owning terminal is focused.
3. Open the in-app notification panel to confirm whether the item was retained.

Terminal bell does not work#

1. Run printf '\a' directly in the terminal.
2. Check the selected terminal backend's bell support.
3. Prefer dev notify when you need durable history and exact terminal routing.