feat(cli): add macOS run-event notifications (interactive only)#19056
feat(cli): add macOS run-event notifications (interactive only)#19056LyalinDotCom wants to merge 15 commits intomainfrom
Conversation
Summary of ChangesHello @LyalinDotCom, I'm Gemini Code Assist1! 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 introduces a significant user experience improvement for macOS users of the interactive Gemini CLI by adding native notifications. The primary goal is to alert users to critical interactive prompts or the completion of a response when the CLI application is not in focus, thereby reducing the need for constant monitoring. The implementation carefully considers user preferences, platform specifics, and terminal capabilities to deliver a reliable and non-intrusive notification system. Highlights
Changelog
Using Gemini Code AssistThe 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
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 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. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a valuable feature by adding macOS native notifications for interactive runs, improving user awareness for action-required states and response completions. The implementation is robust, with thoughtful handling of different terminal capabilities (OSC 9 with a BEL fallback) and unreliable focus event reporting. The logic for triggering notifications is comprehensive and well-tested. I've identified one area for improvement regarding string truncation to ensure correct handling of multi-byte Unicode characters, which is detailed in a specific comment. Overall, this is a great addition to the CLI.
| export function truncateForMacNotification( | ||
| input: string, | ||
| maxChars: number, | ||
| ): string { | ||
| if (maxChars <= 0) { | ||
| return ''; | ||
| } | ||
|
|
||
| const normalized = normalizeText(input); | ||
| if (normalized.length <= maxChars) { | ||
| return normalized; | ||
| } | ||
|
|
||
| if (maxChars <= ELLIPSIS.length) { | ||
| return ELLIPSIS.slice(0, maxChars); | ||
| } | ||
|
|
||
| return `${normalized.slice(0, maxChars - ELLIPSIS.length)}${ELLIPSIS}`; | ||
| } |
There was a problem hiding this comment.
The current implementation of truncateForMacNotification uses string.length and string.slice, which operate on UTF-16 code units. This can lead to incorrect truncation and broken characters if the notification text contains multi-byte Unicode characters like emojis or certain international characters.
To ensure correct handling of all Unicode characters, it's better to operate on grapheme clusters.
export function truncateForMacNotification(
input: string,
maxChars: number,
): string {
if (maxChars <= 0) {
return '';
}
const normalized = normalizeText(input);
const graphemes = Array.from(normalized);
if (graphemes.length <= maxChars) {
return normalized;
}
if (maxChars <= ELLIPSIS.length) {
return ELLIPSIS.slice(0, maxChars);
}
return `${graphemes.slice(0, maxChars - ELLIPSIS.length).join('')}${ELLIPSIS}`;
}References
- When truncating strings that may contain multi-byte Unicode characters (e.g., emojis), use methods that operate on grapheme clusters (like
Intl.SegmenterorArray.from()) instead of UTF-16 code units (string.length,string.slice()) to prevent character splitting.
There was a problem hiding this comment.
please revert and switch to a standard shared helper method for truncation
There was a problem hiding this comment.
fixed: replaced bespoke truncation path with shared helpers from ui/utils/textUtils and removed the old macosNotifications module. (commit b8ba941)
gemini-cli
bot
added
priority/p2
|
Size Change: +12.1 kB (+0.05%) Total Size: 24.4 MB
ℹ️ View Unchanged
|
jackwotherspoon
left a comment
jackwotherspoon
left a comment
There was a problem hiding this comment.
What do you think about having the setting be general.enableNotifications instead of general.enableMacOsNotifications to be future proof.
A single setting vs 3 seems nicer to me.
docs/get-started/configuration.md
Outdated
| - **Description:** Enable update notification prompts. | ||
| - **Default:** `true` | ||
|
|
||
| - **`general.enableMacOsNotifications`** (boolean): |
There was a problem hiding this comment.
I think i would rather see this be future proof. With the description saying macOS only.
That way we don't have 3 different settings in our docs and /settings.
We already do a darwin check i believe so for now this setting would be a no-op for non macOS users.
| - **`general.enableMacOsNotifications`** (boolean): | |
| - **`general.enableNotifications`** (boolean): |
There was a problem hiding this comment.
fixed: renamed to general.enableNotifications and updated schema/docs/settings UI. behavior remains darwin-gated and no-op on non-macOS. (commit b8ba941)
packages/cli/src/ui/AppContainer.tsx
Outdated
| !!validationRequest || | ||
| !!customDialog; | ||
|
|
||
| const pendingAttentionNotification = useMemo( |
There was a problem hiding this comment.
this needs to be its own hook and needs to be refactored to be integrated with hooks
There was a problem hiding this comment.
fixed: moved notification side effect and transition logic out of AppContainer into useRunEventNotifications and integrated it with existing hooks/selectors. (commit b8ba941)
| export function supportsOsc9Notifications( | ||
| env: NodeJS.ProcessEnv = process.env, | ||
| ): boolean { | ||
| if (env['WT_SESSION']) { |
There was a problem hiding this comment.
there has to be a better way to check for OSC9 notification support. this is way too hard coded and has dupes (e.g. WzTerm and wezterm). Typically there are capability detection queries you can run or other terminal capabilities you can link to. For example, do Kitty compatible terminals typically support this?
There was a problem hiding this comment.
fixed: tightened OSC9 support detection and now pass terminal capability-query signal (terminalName from terminalCapabilityManager) into the decision path. (commit b8ba941)
| const ELLIPSIS = '...'; | ||
| const BEL = '\x07'; | ||
| const OSC9_PREFIX = '\x1b]9;'; | ||
| const MAX_OSC9_MESSAGE_CHARS = 220; |
There was a problem hiding this comment.
fixed: removed the hardcoded 220 literal. OSC9 payload limit is now derived from title/subtitle/body caps plus separator length. (commit b8ba941)
| const PM_START_CODE = '^'.charCodeAt(0); | ||
| const APC_START_CODE = '_'.charCodeAt(0); | ||
|
|
||
| let graphemeSegmenter: Intl.Segmenter | undefined; |
There was a problem hiding this comment.
need to reuse existing truncation code rather than writing another version.
There was a problem hiding this comment.
fixed: reused existing shared truncation/sanitization utilities instead of maintaining a separate truncation implementation. (commit b8ba941)
| const originalPlatform = process.platform; | ||
| const originalTermProgram = process.env['TERM_PROGRAM']; | ||
| const originalTerm = process.env['TERM']; | ||
| const originalItTermSessionId = process.env['ITERM_SESSION_ID']; |
There was a problem hiding this comment.
ITERM_SESSION_ID should not be used as it will mean an vscode window opened from iterm will be incorrectly classified as iterm
There was a problem hiding this comment.
fixed: removed ITERM_SESSION_ID usage from detection/tests to avoid VSCode launched from iTerm misclassification. (commit b8ba941)
|
|
||
| beforeEach(() => { | ||
| vi.resetAllMocks(); | ||
| delete process.env['TERM_PROGRAM']; |
There was a problem hiding this comment.
this is not how env vars are mocked in the project
There was a problem hiding this comment.
fixed: updated tests to follow project env-mocking conventions via vi.stubEnv and vi.unstubAllEnvs. (commit b8ba941)
| @@ -0,0 +1,276 @@ | |||
| /** | |||
There was a problem hiding this comment.
This whole file is named wrong OSC9 works on terminals that are not Mac.
There was a problem hiding this comment.
fixed: renamed the module from macosNotifications.ts to terminalNotifications.ts to match OSC9 plus BEL terminal transport scope. (commit b8ba941)
| return true; | ||
| } | ||
|
|
||
| if (env['ITERM_SESSION_ID']) { |
There was a problem hiding this comment.
you must use TERM_PROGRAM for ITERM so avoid the IDEs launched from ITERM issue.
There was a problem hiding this comment.
fixed: iTerm detection now relies on TERM_PROGRAM and terminal-name signatures; ITERM_SESSION_ID check is removed. (commit b8ba941)
gemini-cli
bot
added
the
🔒 maintainer only
|
I caught a few things I want to clean up before we merge. [ ] Refactor AppContainer: I realized I put too much one-off notification logic here. I’m going to move the state transitions into a dedicated hook composed of our existing selectors. [ ] DRY up string handling: I'm going to swap my bespoke string pipeline for the shared truncation/sanitization helpers we already have. [ ] Fix logic duplication: I need to reuse the existing confirmation queue/head selection logic rather than duplicating the pending-tool traversal. [ ] Terminal Capabilities: I'll replace the hardcoded OSC9 allowlists with actual capability detection (or at least centralized constants) and document the fallback paths. [ ] Magic Numbers: I need to remove the magic numbers (like the 220 cap) and encode them as documented constraints. [ ] Tests: I need to align the tests with vi.stubEnv conventions and add behavior tests for the cooldown/repeated prompts to ensure I haven't regressed notification delivery. [ ] Naming: I’m going to rename the scope to reflect transport semantics (OSC9 + BEL) rather than platform branding. |
|
Following up on my checklist, here is what I have fixed:
Implemented in commit |
3 participants
Summary
This PR adds macOS notifications for interactive Gemini CLI runs and tightens trigger behavior so notifications only fire for in-run events that require user awareness.
Fixes #14696
Final Behavior
general.enableMacOsNotifications(default:false).process.platform === 'darwin').Responding -> IdleNotification Transport
Focus Handling
hasReceivedFocusEvent) so notifications still work when terminals do not emit focus events consistently.Settings / Schema / Docs
general.enableMacOsNotificationsto settings schema and docs.Tests
Updated and added tests across:
packages/cli/src/utils/macosNotifications.test.tspackages/cli/src/ui/AppContainer.test.tsxpackages/cli/src/ui/hooks/useFocus.test.tsxpackages/cli/src/gemini.test.tsxValidated suites include:
npm test -w @google/gemini-cli -- src/utils/macosNotifications.test.tsnpm test -w @google/gemini-cli -- src/ui/AppContainer.test.tsx src/ui/hooks/useFocus.test.tsxnpm test -w @google/gemini-cli -- src/gemini.test.tsx