Notifications

AgentOS notifies you when sessions need input—so you can step away and come back at the right time.

Why Notifications Matter

AI coding agents often need approval or input:

• "Apply these changes? [Y/n]"
• "Continue with this approach?"
• "Enter your API key:"

Without notifications, you'd have to constantly check each session. With notifications, you can work on other things and respond when needed.

Enabling Notifications

1. Click the bell icon in the header
2. Your browser asks for notification permission
3. Click Allow

That's it. You'll now receive alerts when any session enters "waiting" status.

What Triggers Notifications

AgentOS monitors terminal output for waiting patterns:

The status detection runs continuously and triggers notifications within seconds of a prompt appearing.

Notification Types

Browser Notifications

Standard push notifications that appear in your system notification center:

• Work when AgentOS is in a background tab
• Work when browser is minimized
• Include session name and prompt preview

Sound Alerts

Optional audio feedback:

1. Click the bell icon
2. Enable Sound alerts
3. A chime plays when sessions need attention

Useful when you're working nearby but not watching the screen.

Mobile Notifications

AgentOS is a PWA (Progressive Web App) that supports mobile notifications:

iOS

1. Open AgentOS in Safari
2. Tap Share → Add to Home Screen
3. Open the app from your home screen
4. Enable notifications when prompted

Note: iOS requires the PWA to be installed for notifications to work.

Android

1. Open AgentOS in Chrome
2. Tap the menu → Add to Home Screen
3. Enable notifications when prompted

Android notifications work both in-browser and as an installed PWA.

Notification Behavior

When Active

If AgentOS is your active tab, you'll see the status change in real-time. Notifications still fire for background awareness.

When Backgrounded

Notifications appear in your system notification center. Click to jump directly to the waiting session.

Multiple Sessions

Each session triggers its own notification. If several sessions need attention, you'll receive multiple alerts.

Status Indicators

The UI shows session status with colored indicators:

Notifications fire when status changes to Waiting.

How Status Detection Works

AgentOS scans terminal output for patterns:

1. Waiting patterns - Prompts like [Y/n], Continue?
2. Busy indicators - Words like "thinking", spinners
3. Activity analysis - Distinguishes bursts from sustained work

A 2-second cooldown prevents false alerts when agents pause briefly.

Troubleshooting

Notifications Not Appearing

1. Check browser permissions

   • Click the lock icon in the address bar
   • Ensure notifications are allowed

2. Check system settings

   • macOS: System Settings → Notifications → Browser
   • Windows: Settings → Notifications → Browser
   • Ensure notifications aren't in Do Not Disturb mode

3. Reinstall PWA (mobile)

   • Remove the app from home screen
   • Add it again and re-enable notifications

Too Many Notifications

If you're getting too many alerts:

• Close sessions you're not actively using
• Kill idle sessions from the session menu

Delayed Notifications

Notifications should appear within 2-3 seconds of a prompt. If delayed:

• Check your internet connection
• Ensure the browser tab isn't throttled (keep it as a pinned tab)

Best Practices

Keep Sessions Focused

One task per session. This makes notifications more meaningful—you know exactly what needs attention.

Use Session Names

Rename sessions to describe their task. Notifications include the session name, so descriptive names help you prioritize.

Close Finished Sessions

Don't leave completed sessions running. They can produce false-positive waiting states.

Check Before Stepping Away

Glance at your sessions before leaving. If any show "waiting", handle them first or you'll get a notification immediately.

Notification-Friendly Workflow

1. Start your AI agent on a task
2. Enable notifications
3. Switch to other work or step away
4. Get notified when input needed
5. Review and approve/respond
6. Repeat

This async workflow lets you manage multiple agents efficiently without constant monitoring.