Notifications

When you’re running agents across multiple projects, you need to know when something needs your attention - without constantly checking each board. Kangentic uses native desktop notifications, sidebar badges, and auto-focus to keep you informed. Notifications tell you when an agent needs you; the Agent Monitor shows you everything running, across every project.

Desktop Notifications

Kangentic sends native OS notifications when an agent needs attention and you can’t already see it - either the window is minimized/unfocused, or a different project is active.

Notification Triggers

Event	Notification Body
Agent idle	Agent has stopped and may need input (includes permission prompts)
Session crash	Agent process exited with a non-zero exit code
Plan completion	Agent finished planning and auto-moved to the next column
Spawn stalled	A task spawn is waiting too long on the git queue while its worktree is prepared

The task title is the notification title, and the project name is the body.

Click Behavior

Clicking a notification:

1. Brings the Kangentic window to the foreground
2. Switches to the correct project
3. Opens the task detail dialog for that task

This makes notifications actionable - one click takes you directly to the agent that needs attention.

Taskbar Flash

On Windows, the taskbar icon also flashes when a notification fires, so you’ll notice even if you miss the popup.

Cooldown

A 10-second per-session cooldown prevents repeated notifications from the same agent. If an agent goes idle, fires a notification, then goes idle again within 10 seconds, no second notification is sent.

Notification Settings

Settings > Notifications gives each of the four events - Agent Idle, Agent Crash, Plan Complete, and Spawn Stalled - its own channel dropdown: Both (desktop and in-app toast), Desktop only, Toast only, or Off. Agent Crash covers a session ending unexpectedly, and its two channels differ on purpose: the desktop alert fires on error exits only, while the toast also reports clean exits. Two more settings shape the in-app toasts: Toast Auto-Dismiss (how long a toast stays visible, 1-30 seconds) and Max Visible Toasts (how many stack on screen at once, 1-10).

Note

These map to the notifications.desktop.* and notifications.toasts.* config keys - see the Configuration Reference for the full list and defaults.

Idle Badges

The sidebar shows all your projects in a list. When an agent goes idle on a project you’re not currently viewing, an idle badge appears next to that project’s name. This tells you at a glance that an agent has stopped - it may have finished, hit a permission prompt, or encountered an error.

Click the project to switch to it and see what the agent needs.

Auto-Focus Idle Session

When enabled, Kangentic automatically switches to an agent’s terminal tab when that agent goes idle. This means you’ll immediately see what the agent is waiting for - whether it’s asking a question, requesting permission, or showing its final output.

This behavior is controlled by the autoFocusIdleSession setting (disabled by default). You can turn it on in Settings if you want the terminal to auto-switch when an agent goes idle. When disabled, idle agents show an amber tab indicator instead.

Real-Time Card Indicators

Every task card on your board shows the agent’s current state with real-time updates:

Indicator	Meaning
Pulsing spinner	Agent is actively thinking or running tools
Static icon	Agent is idle - finished, waiting, or needs input
Error highlight	Agent encountered an error
”Queued” label	Waiting for a concurrent session slot to open

The Agent Monitor speaks the same vocabulary for every project at once, so the state you learn to read on cards carries over.

Multi-Project Awareness

The combination of desktop notifications, idle badges, taskbar flash, and auto-focus means you can run agents across several projects and trust that you’ll be notified when attention is needed. A typical workflow:

1. Set up tasks across 2-3 projects
2. Work on your active project while agents run in the background
3. Notice the notification or idle badge when a background agent needs you
4. Click the notification (or project in the sidebar) to switch and respond
5. Return to your active project

Instead of waiting to be told, you can also watch directly: the Agent Monitor (Ctrl+Shift+M / Cmd+Shift+M) lists every project’s sessions in one view, with live output peeks per card.

See Multi-Project Support for more on managing multiple projects.

Status Bar

The status bar runs along the bottom of the window with at-a-glance metrics for the current project (the Agent Monitor’s summary tiles are the machine-wide counterpart):

Metric	Description
Agents	Count of actively running agent sessions (green when above zero), plus any queued count
Tasks	Count of active (non-done) tasks on the board

Token and cost metrics moved off the status bar in v0.30.0: they now live in the Usage Stats Dashboard, a full-page view opened from the title-bar chart icon or Ctrl+Shift+U / Cmd+Shift+U, with time ranges, scopes, and per-model / per-agent breakdowns. Hide the status bar entirely with the Status Bar Visible toggle under Settings > Board.

In-App Announcements

Every other surface on this page reports on your agents. Announcements are the one thing the app tells you about itself: a slim banner above the board carrying occasional product news, such as a call for mobile-app beta testers or a store launch.

The banner has two controls. Learn more opens the full message in a dialog, which can carry titled sections, external links, and a large scannable QR code beside any link meant for your phone. The X dismisses that announcement for good on this machine, and dismissals are per announcement, so retiring one does not silence the next.

The megaphone, the badge, and the history

The banner is single-use, so the megaphone in the title bar is the permanent way back in. It sits at the right end of the icon row, next to the update-available indicator: both of those are the app telling you something, as opposed to the monitor and stats buttons to their left, which report on your running work. Unlike every other conditional control in that row it is always mounted, so nothing shifts position when an announcement arrives.

A small count badge on the glyph is the number of unread announcements, and the megaphone itself warms to the attention color while any remain. Read is not the same as dismissed, and the two are tracked separately on purpose: closing the banner with the X hides the strip but leaves the announcement unread, so the badge stays lit until you have actually opened it. The megaphone means “there is something you have not read”, not “there is a banner”.

Clicking it opens the Announcements list: every announcement this machine has ever had active, most recently seen first, read and unread alike. Each row shows an unread dot, the announcement’s own publication date, and a chevron. Clicking a row opens the same full message dialog the banner’s Learn more does, on top of the list, so closing the message returns you to the list rather than out of it. Opening a message marks it read, and only the first open stamps the timestamp, so revisiting one never rewrites when you first read it.

The list is the client’s own archive rather than a live query, which is what makes it work on a cold or offline launch: the live feed is empty for the first 10 seconds of every launch and stays empty with no network, but the archive is already on disk. It also outlives the feed, so an announcement the team retires upstream is still readable here. Only announcements that were targeted at this machine in the first place ever enter it, and it is capped at 50 entries. An announcement edited upstream refreshes in place rather than arriving as a second copy.

Where the feed comes from

There is no announcement server and no account. The app fetches a static announcements.json file from the public GitHub repository, 10 seconds after launch and every 4 hours after that. Filtering happens in the main process before anything reaches the window: each entry carries an inclusive version window and an optional desktop-platform list, so an announcement can be aimed at the builds it actually applies to.

That design has a deliberate consequence for anyone running Kangentic disconnected. An unreachable, malformed, or empty feed simply means no banner. Nothing is retried loudly, nothing is logged as an error, and no telemetry is emitted for the attempt. A fully offline or self-hosted setup loses nothing but the announcements themselves.

Note

Dismissals persist in the dismissedAnnouncementIds global config key, pruned on write to the ids still in the active feed, so the list stays bounded. Read state cannot live there for exactly that reason, so it rides in the archive instead: a small JSON sidecar beside your config file, holding each entry plus when it was first seen and first read. A KANGENTIC_ANNOUNCEMENTS_URL environment variable points the poll at a different feed, which exists for testing against a local fixture.

Next steps

Next: Activity Detection - the underlying state that drives notifications.

See also:

• Agent Monitor - watch every project’s sessions instead of waiting for an alert
• Multi-Project - cross-project sidebar badges
• Settings - configure which states trigger which alerts
• Push Notifications - the same alerts on your phone, from the companion app