Use OSC 777 for terminal notifications

[jackyliuxx]

Summary

Change terminal notifications fallback from BEL to OSC 777, which is supported by many terminals including Ghostty, Kitty, WezTerm, Konsole, etc. For known terminals which does not support OSC 777, use OSC 9 or BEL.
Allow users to choose which one to use in settings, if it doesn't work for their terminals.

Details

• Use OSC 777 for terminal notifications with the follow exception.
  • Use OSC 9 for known terminals which only supports OSC 9:
    • iTerm2
  • Use BEL for known terminals which does not support OSC 777 nor OSC 9:
    • Alacritty
    • Apple Terminal
    • VS Code Terminal
    • Window Terminal
• Add DCS passthrough sequences when in Tmux or GNU screen.
• Add "Terminal Notification Method" in settings to allow users to choose between OSC 9, OSC 777 and BEL, if the default value doesn't work for them.
• Change "Enable Notifications" to "Enable Terminal Notifications" in settings for clarity.

Related Issues

Closes #25202
Related to #17819

How to Validate

1. Run Gemini CLI in a terminal supports OSC 777 or OSC 9 (tested with Konsole and Kitty on Linux).
2. Set "Enable Terminal Notifications" to true.
3. Change "Terminal Notification Method" if needed.
4. Ask something and waiting for response.
5. See the notification when responded.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly upgrades the terminal notification system by adopting OSC 777 as the preferred method for most terminals, enhancing user experience with more reliable and feature-rich notifications. It also provides users with greater control over their notification preferences through new settings, ensuring compatibility across a wider range of terminal environments, including multiplexers like Tmux and GNU Screen.

Highlights

• Enhanced Terminal Notifications: Terminal notifications now primarily use OSC 777, offering broader support across modern terminals like Ghostty, Kitty, and WezTerm, while falling back to OSC 9 for iTerm2 and BEL for terminals like Alacritty, Apple Terminal, VS Code Terminal, and Windows Terminal.
• User-Configurable Notification Method: A new setting, 'Terminal Notification Method', has been introduced, allowing users to explicitly choose between 'auto' (default behavior), 'OSC 9', 'OSC 777', or 'Bell' if the automatic detection does not suit their terminal setup.
• Improved Compatibility: DCS passthrough sequences have been added to ensure terminal notifications function correctly when running within Tmux or GNU Screen sessions.
• Refactored Terminal Capability Detection: The internal logic for detecting terminal capabilities has been refactored into specific helper functions for various terminal types (e.g., isTmux, isITerm2, isAlacritty), improving clarity and maintainability.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a new notificationMethod setting, allowing users to choose between auto-detection, OSC 9, OSC 777, or a simple bell for terminal notifications. It also refactors terminal capability detection and adds passthrough support for terminal multiplexers like tmux and GNU Screen. Review feedback identifies a bug in the GNU Screen passthrough sequence where escape characters need to be doubled and notes a potential regression where defaulting to OSC 777 for unknown terminals might break notifications for users of older terminal emulators.

[jackyliuxx]

(comment from ./scripts/review.sh 25300)
Excellent PR! The logic is sound, the tests cover all the new behavior (including the new terminal capability checks, explicit methods, and the passthrough wrappers), and the typecheck/lint/tests pass perfectly. The attention to detail with the semicolon replacement for OSC 777 is great. Since I cannot approve my own PR, I am leaving this comment to indicate that it looks good to go.

[jacob314]

[jacob314]

Summary

This PR introduces robust and configurable terminal notification handling. It adds a new general.notificationMethod setting, allowing users to explicitly choose between 'auto', 'osc9', 'osc777', and 'bell'. The PR properly implements OSC 777 as the new default for unknown terminals and improves the detection logic for various terminal emulators (Tmux, Screen, iTerm2, Alacritty, VSCode, Apple Terminal, and Windows Terminal). The tests are well-updated and the test suite passes smoothly.

Findings

• Critical: None.
• Improvements:
  • Kitty Terminal Support: In the previous version of TerminalCapabilityManager, there was explicit support for kitty, wezterm, and ghostty to send them OSC 9 notifications. In this PR, they have been dropped from auto-detection and will now fall back to OSC 777. While wezterm and ghostty support OSC 777, kitty does not natively support OSC 777 (it supports OSC 9 and its own OSC 99). This means Kitty users might lose notifications on the auto setting. I recommend bringing back an isKitty() (and potentially wezterm/ghostty) check to the capability manager and routing it to emitOsc9Notification(content) or better yet OSC 99 within the auto-detection block.

Conclusion

Approved.

(Note: This review was conducted by the Gemini CLI /review-frontend and reviewed manually by Jacob.)

[jackyliuxx]

• Kitty Terminal Support: In the previous version of TerminalCapabilityManager, there was explicit support for kitty, wezterm, and ghostty to send them OSC 9 notifications. In this PR, they have been dropped from auto-detection and will now fall back to OSC 777. While wezterm and ghostty support OSC 777, kitty does not natively support OSC 777 (it supports OSC 9 and its own OSC 99). This means Kitty users might lose notifications on the auto setting. I recommend bringing back an isKitty() (and potentially wezterm/ghostty) check to the capability manager and routing it to emitOsc9Notification(content) or better yet OSC 99 within the auto-detection block.

Although is not officially documented, Kitty actually supports OSC 777 since 2022 (0.24.0). I also commented in #25200. Using Kitty's own OSC 99 could be better but it looks more complicated and I personally don't use Kitty, so I'll leave it to someone else.