Skip to content

Conversation

@linw1995
Copy link
Owner

Closes #135

Summary

Implements OSC 9 escape sequence support for desktop notifications in the TUI, addressing the need for user notification when:

  • Subagent requires user confirmation/feedback
  • Long-running tasks complete
  • Terminal is not in focus

Changes

Core Implementation

  • New notifications module (crates/coco-tui/src/notifications.rs):
    • OSC 9 escape sequence backend (default)
    • External command backend support for custom notification handlers
    • Proper payload sanitization and length limits

TUI Integration

  • Focus tracking (app.rs, events.rs):

    • Added FocusGained/FocusLost event handling
    • Track terminal focus state to enable "only_when_unfocused" mode
  • Chat component (components/chat.rs):

    • Notify when reply is ready (non-tool-use responses)
    • Notify when action is required (tool permissions, text edit confirmations)
    • Configurable notification behavior based on focus state

Configuration

  • New config options (src/config/ui.rs):
    [ui.notifications]
    enabled = true              # Enable/disable notifications
    only_when_unfocused = true  # Only notify when terminal loses focus
    backend = { type = "osc9" }  # or external_command

Usage

Default (OSC 9) - works with modern terminal emulators:

[ui.notifications]
enabled = true
only_when_unfocused = true

Custom notification command:

[ui.notifications.backend]
type = "external_command"
executable = "notify-send"
args = ["--app-name", "coco", "--category", "im.received"]

- Add notifications module with OSC-9 escape sequence support
- Notify when AI reply is ready with optional summary
- Notify when user action is required (tool permissions, text edits)
- Sanitize notification payloads to prevent terminal injection
- Add terminal focus tracking with FocusGained/FocusLost events
- Add notifications.enabled and only_when_unfocused config options
- Only send desktop notifications when terminal is unfocused (optional)
- Default to enabled notifications with only_when_unfocused=true
- Add NotificationBackend enum with OSC-9 and external command variants
- Send notifications via configurable external commands with JSON payload
- Normalize notification fields with optional semicolon replacement
@codecov-commenter
Copy link

codecov-commenter commented Jan 24, 2026

Codecov Report

❌ Patch coverage is 41.40969% with 133 lines in your changes missing coverage. Please review.
✅ Project coverage is 48.83%. Comparing base (a46f02c) to head (9027a9a).
⚠️ Report is 4 commits behind head on dev.

Files with missing lines Patch % Lines
crates/coco-tui/src/components/chat.rs 0.00% 67 Missing ⚠️
crates/coco-tui/src/notifications.rs 49.55% 57 Missing ⚠️
crates/coco-tui/src/app.rs 0.00% 8 Missing ⚠️
src/config.rs 96.00% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##              dev     #139      +/-   ##
==========================================
- Coverage   50.22%   48.83%   -1.40%     
==========================================
  Files          93       95       +2     
  Lines       25033    26076    +1043     
==========================================
+ Hits        12574    12734     +160     
- Misses      12459    13342     +883     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@linw1995 linw1995 added the enhancement New feature or request label Jan 24, 2026
- Enable focus change events when entering alternate screen
- Disable focus change events when restoring terminal
- Support FocusGained/FocusLost detection for notification filtering
@linw1995 linw1995 merged commit 6ca00d2 into dev Jan 24, 2026
3 checks passed
@linw1995 linw1995 deleted the feature/osc9-notification branch January 24, 2026 08:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature: Support OSC 9 escape sequence for user notifications

3 participants