Add system notifications

[NaccOll]

Related GitHub Issue

Closes: #5015 (comment)

Roo Code Task Context (Optional)

Description

Implementing system notifications similar to Kilo. But it is triggered only when vscode is not the focused window.

Currently, different system notifications are displayed to users for errors, pending user approval, and task completion.

However, user customization of issues, priority levels, and the ability to directly complete actions when prompted by system notifications are not yet implemented.

Test Procedure

1. Enable System Notifications in setting
2. chat and trigger tool use
3. system notification will display

You can try all scene with sound effects occur

• api_req_failed
• mistake_limit_reached
• followup
• tool
• browser_action_launch
• command
• use_mcp_server
• completion_result

Pre-Submission Checklist

• Issue Linked: This PR is linked to an approved GitHub Issue (see "Related GitHub Issue" above).
• Scope: My changes are focused on the linked issue (one major feature/fix per PR).
• Self-Review: I have performed a thorough self-review of my code.
• Testing: New and/or updated tests have been added to cover my changes (if applicable).
• Documentation Impact: I have considered if my changes require documentation updates (see "Documentation Updates" section below).
• Contribution Guidelines: I have read and agree to the Contributor Guidelines.

Screenshots / Videos

Documentation Updates

Additional Notes

Get in Touch

---

Important

Adds system notifications for various events with platform-specific logic and UI settings, enabling users to receive alerts for important actions.

• Behavior:
  • Adds system notifications for events like API request failures, mistake limits, follow-ups, tool requests, browser actions, commands, MCP server usage, and task completions.
  • Notifications can be enabled/disabled via systemNotificationsEnabled in global-settings.ts and ClineProvider.ts.
  • showSystemNotification() function in showSystemNotification.ts handles notification display with debounce.
• UI Components:
  • Updates NotificationSettings.tsx to include system notification settings and test button.
  • ChatView.tsx triggers notifications for specific events.
• Platform Support:
  • Implements platform-specific notification logic in notifications/index.ts for macOS, Windows, and Linux.
• Localization:
  • Adds system notification strings to multiple locale files including settings.json for various languages.

^{This description was created by for 5ec272163d0264a2250c14bab639e60b068baa56. You can customize this summary. It will automatically update as commits are pushed.}

[roomote]

Thank you for your contribution! I've reviewed the system notification implementation and found several issues that need attention before this can be merged.

[roomote]

Missing error handling feedback to users. When notifications fail, users have no way to know. Consider implementing a fallback mechanism:

Suggested change

	console.error("Could not show system notification", error)
	} catch (error) {
	console.error("Could not show system notification", error);
	// Fallback to VSCode's built-in notification
	vscode.window.showInformationMessage(options.message);
	}

[roomote]

The Windows implementation hardcodes "Roo Code" which might not work correctly in all configurations. Could we make this configurable or detect the actual application name?

[roomote]

The 100ms debounce is hardcoded. Would it be beneficial to make this configurable for different use cases?

[roomote]

The NotificationOptions interface is quite basic. Based on the issue requirements, shouldn't it support priority levels and action buttons?

[NaccOll]

Not supported yet

[roomote]

Good integration with the chat events! However, consider adding test coverage for these notification triggers to ensure they work correctly across different scenarios.

[mrubens]

I like the idea of this a lot! I'm trying on my Mac though and the test system notification isn't working. Any ideas?

[NaccOll]

@mrubens I need to confirm whether the click test on the settings page works.

Unlike Kilo, my commits don't display notifications when the VSCode window is focused. This is because I'm using the secondary sidebar, and the system notifications obscure my send message button.

[NaccOll]

@mrubens

I tested it on my Mac Mini, but I still couldn't get notifications, and Kilo's notification feature didn't work either.

The reason is that the following script no longer works on macOS:

osascript -e 'display notification "hello" with title "word" sound name "Frog" '

If I change it to:

osascript -e 'display alert "hello" message "world"'

Then I can call the alert function.

[NaccOll]

@mrubens After more detailed testing, it is found that notifications can only be displayed when the script editor is allowed to notify and the user is not in do not disturb mode. This should be a limitation of macOS itself.

[daniel-lxs]

Thank you for implementing system notifications! I've reviewed the changes and found some issues that need attention before merging.

[daniel-lxs]

Is the 100ms debounce intentional? This could cause distinct notifications to be dropped if they occur within the same window. For example, if both a "tool request" and "command" notification trigger within 100ms, only the last one will be shown.

Consider using throttling instead of debouncing, or implementing message-based deduplication to avoid losing important notifications.

[NaccOll]

This design is inspired by Kilo. Switching to throttling is indeed more reasonable, as it helps send notifications faster. However, I need to introduce throttle-debounce as a dependency—is that acceptable?

Additionally, the two different types of notifications you described are unlikely to trigger within 100 milliseconds.
This is because notifications are limited to completion, failure, and waiting for user input—these three scenarios are unlikely to occur within 100 ms. Moreover, unlike Kilo, my notification requires VS Code not to be the currently focused window in order to trigger.

[daniel-lxs]

In that case I think we can keep it like this unless we get reports of it causing issues

[daniel-lxs]

The Linux implementation assumes notify-send is available but doesn't handle the case where it's not installed. Consider checking for the binary first or providing a helpful error message:

Suggested change

	throw new Error(`Failed to show Linux notification: ${error}`)
	} catch (error: any) {
	if (error.code === 'ENOENT') {
	throw new Error('notify-send is not installed. Please install libnotify-bin (apt install libnotify-bin on Debian/Ubuntu)')
	}
	throw new Error(`Failed to show Linux notification: ${error}`)
	}

[NaccOll]

fix

[daniel-lxs]

Thank you @NaccOll!

[mrubens]

I still can't get this to work on Mac. I like the idea of system notifications but I think we have to make it more obvious to people how to set it up, otherwise it just seems broken.

[NaccOll]

I still can't get this to work on Mac. I like the idea of system notifications but I think we have to make it more obvious to people how to set it up, otherwise it just seems broken.

I have a Mac mini, but I'm not familiar with Mac OS, so writing a guide for Mac users is a challenge.

Should I change "display notification" to "display alert"? This won't allow use the various Mac notification settings, but it will avoid the complicated setup process.

[daniel-lxs]

@NaccOll Are the alerts visible if the window is in the background, if so then I think it makes sense.

[NaccOll]

osascript -e 'display alert "hello" message "world"'

Yeah, it work，like follow:

The advantage is that it no requires user configuration; simply toggle it on in RooCode and you'll receive alert when VSCode is not focused. However, even with Do Not Disturb enabled on mac, it still works.

Is there a way to change notification on Mac to alert?

[NaccOll]

Without changing the existing implementation, I followed ⁠https://forum.latenightsw.com/t/trying-to-use-terminal-for-display-notification/5068/6⁠ and enabled notification permissions in the script editor. System notifications are working on my mac mini.

[hannesrudolph]

notification permissions in the script editor is not a sollution that works IMO. Closing.