Notifications and approvals
The notification inbox lets you leave a running task without losing its next question or result. Agent chats and terminals report structured lifecycle events when their provider supports them; the app groups those events across workspaces.
Open the inbox with ⌘I.
Three inbox views
Section titled “Three inbox views”| View | Purpose |
|---|---|
| Running | Sessions and processes that are actively working |
| Queue | Tasks that need a response, completed, or ended with an error |
| Timeline | Recent notification history, subject to your retention setting |
Queue rows retain their source workspace, project, worktree, and tab. Opening a row returns to that context. If the source worktree was deleted or moved, the app falls back to the closest context that still exists.
What enters the queue
Section titled “What enters the queue”The app can queue:
- Approval requests before a command or tool action.
- Questions and other user-input requests.
- Completed tasks that are ready for review.
- Errors that stopped or changed the task.
Progress-only events remain visible as running state without creating a response item each time. A chat already visible in the foreground may avoid a redundant queue item; you can explicitly send it back to the queue as unread when you want to revisit it.
Providers expose different lifecycle signals. The app uses provider hooks, managed session events, and Chat UI events when available. It does not treat arbitrary terminal output as authoritative approval or completion protocol.
Other feedback surfaces
Section titled “Other feedback surfaces”Not every message belongs in the inbox:
- A top banner handles quick confirmations and actions that need an immediate choice.
- A bottom-right toast reports rich errors and short-lived status without changing your current selection.
- A macOS notification mirrors eligible events when the app is unfocused or when your delivery setting allows it.
These surfaces complement the inbox. A toast can explain a failure while the corresponding task remains in the Queue, and disabling macOS delivery does not disable in-app state.
Work through the queue
Section titled “Work through the queue”Select an item to read its preview without abandoning the inbox. Peek is useful when several agents finish close together: inspect the result, reply when needed, then advance to the next item.
Default inbox shortcuts are contextual:
| Context | Shortcut | Result |
|---|---|---|
| Anywhere | ⌘I | Open the notification inbox |
| Anywhere | ⌘⌥J | Select an older notification |
| Anywhere | ⌘⌥K | Select a newer notification |
| Current chat | ⌘⌥U | Put the chat in the queue as unread |
| Current chat | ⌘⌥⌫ | Remove the chat’s queue item |
| Queue | J / K or ↑ / ↓ | Move between rows |
| Queue | Space | Peek at the selected item |
| Queue | ↩ | Open the selected source tab |
| Queue | D | Dismiss the selected item |
| Queue | U | Mark the selected item unread |
| Peek | ↩ | Send the reply and advance |
| Peek | ⌘↩ | Open the source chat |
Change bindings under Settings → Keyboard Shortcuts if they conflict with another workflow.
Approval and input requests
Section titled “Approval and input requests”Before approving an action:
- Check the source workspace and worktree.
- Read the exact command, tool call, file operation, or question.
- Confirm that the action belongs to the task and uses the intended permissions.
- Approve, deny, or reply from the provider surface or supported queue preview.
An auto-submitted or background Git action can still pause for provider approval. Background dispatch changes where the prompt runs; it does not bypass the provider’s permission mode.
Visiting and clearing items
Section titled “Visiting and clearing items”Settings → Notifications → Clear queue items on tab visit controls whether opening the source tab clears its item automatically. Disable it when opening a tab should not imply that you handled the request.
You can always dismiss a queue row directly. Dismissing a notification does not stop its agent, undo its work, or deny a pending provider request; it only removes the inbox item.
Timeline retention controls how much completed notification history remains visible. It does not replace provider conversation history or tab restoration.
macOS notifications
Section titled “macOS notifications”System notifications mirror eligible events outside the app. Choose one delivery mode in Settings → Notifications:
- Always sends eligible system notifications even while the app is focused.
- Only when unfocused avoids duplicate alerts while you are already in the app.
- Never keeps notifications inside the app.
You can configure task-completion and approval/input events separately, including their sounds. Eligible urgent alerts can optionally break through Focus, subject to macOS permission and Focus settings.
If system notifications do not appear:
- Open macOS System Settings → Notifications.
- Select the app.
- Enable notifications and the desired banners, sounds, and Focus behavior.
- Return to the app’s Notification settings and confirm its delivery mode is not Never.
The in-app Queue and Timeline continue to work when system notifications are disabled.