Notifications & Resource Pressure
Relevant source files
The following files were used as context for generating this wiki page:
The Notifications and Resource Pressure systems manage user alerts and optimize application performance under high system load. The notification system interfaces with the operating system to deliver reminders and status updates for background agent tasks. The resource pressure system monitors environmental constraints, such as memory and CPU usage, and triggers corrective actions like stopping idle agents to maintain workspace responsiveness.
Notification Management
The application uses a centralized model to handle OS-level permissions and user preferences. It supports two primary communication channels: audible cues and visual system notifications.
Permission Workflow
To deliver visual alerts, the application must acquire permission from the operating system. The system tracks states including granted, denied, and unsupported.
- Probe: The application checks the current permission status when the notification toggle is active or the window gains focus.
- Request: If the user enables notifications and permission is not yet granted, the application triggers a native request dialog.
- Manual Override: If permissions are denied at the OS level, the UI provides a direct link to System Settings (macOS/Windows) to allow manual re-enabling.
Sources: src/features/settings/ui/SettingsView.tsx:773-787, src/features/settings/ui/SettingsView.tsx:1793-1815
Alert Triggers
Notifications occur based on specific session events and user-defined reminders.
- Agent Completion: Notifies the user when a background agent finishes a turn or requires manual input.
- Reminders: Triggers alerts when a scheduled reminder becomes due.
- System Cues: Plays short sounds for project activity, finished turns, and available updates.
The diagram shows the logic flow for enabling system-level notifications and handling permission states.
Sources: src/features/settings/ui/SettingsView.tsx:773-787, src/features/settings/ui/SettingsView.tsx:1793-1815
Resource Pressure and Performance
The application manages system load by controlling the lifecycle of agent processes and monitoring resource availability.
Idle Agent Limits
Agent CLIs remain active for several minutes after a turn finishes to ensure instant follow-up responses. However, each active agent consumes substantial memory (typically several hundred MB). The application provides an idleAgentLimit setting to prevent excessive resource consumption.
- Monitoring: The system tracks the number of currently idle agents.
- Enforcement: When the count exceeds the user-defined limit, the system stops the agent that has been idle the longest.
- Resumption: Stopped agents automatically restart upon the next user message.
Sources: src/features/settings/ui/SettingsView.tsx:1568-1577
Resource Pressure UI
When system resources reach critical thresholds, the application displays a ResourcePressureNotice. This alert informs the user that performance may be degraded and suggests actions to alleviate the pressure.
Sources: src/features/notifications/ui/ResourcePressureNotice.tsx
Management Configuration
The following table describes the configuration options for managing notifications and resources.
| Option | Type | Default | Description |
|---|---|---|---|
notificationsEnabled | Boolean | true | Enables/disables OS-level visual alerts. |
soundsEnabled | Boolean | loadSoundsEnabled | Enables/disables audible cues for app events. |
idleAgentLimit | Integer | 3 | Maximum number of idle agent processes to keep in memory. |
keepAwake | Enum | off | Prevents screen dimming while agents are running or the app is open. |
Sources: src/features/settings/ui/SettingsView.tsx:771-855, src/features/settings/ui/SettingsView.tsx:1572-1577
Implementation Details
Agent Enforcement Logic
The following sequence illustrates how the system enforces resource limits on background processes.
The diagram represents the execution flow when the system checks and enforces limits on idle background processes to conserve memory.
Sources: src/features/settings/ui/SettingsView.tsx:1576-1577
Notification Preference Storage
const onNotificationsEnabled = (next: boolean) => {
saveNotificationsEnabled(next);
setNotificationsEnabled(next);
if (!next) return;
void requestNotificationPermission().then(setNotificationPermission);
};
This function saves the user's notification preference and conditionally triggers the OS permission request.
Sources: src/features/settings/ui/SettingsView.tsx:782-787
Summary
The Notifications & Resource Pressure system ensures users stay informed of asynchronous task progress while safeguarding system stability. By coordinating OS permissions and managing background process lifecycles, Rebase provides a responsive environment that adapts to hardware constraints.