Skip to content

Latest commit

 

History

History
91 lines (70 loc) · 4.36 KB

IMPLEMENTATION_NOTES.md

File metadata and controls

91 lines (70 loc) · 4.36 KB

Status Notification Audio System - Implementation Notes

Overview

This implementation adds audio notifications to the Agent Callisto 2 terminal plugin for status updates and completion messages. The system is designed to provide unobtrusive audio feedback for important terminal events without overwhelming the user.

Research Summary

Claude Code Plugins / Functions

Claude's AI assistant can use various "tools" or "functions" that provide additional capabilities beyond text generation. In the context of this project, the goal was to implement a similar concept for terminal notifications - providing audio feedback at appropriate moments.

Design Goals

  1. Selective Notifications: Play sounds only for meaningful events (completions, status updates, requests for approval)
  2. Avoid Spam: Don't play sounds for every line of output
  3. Pseudo-Random Selection: Vary the audio to make notifications less monotonous
  4. User Control: Allow users to enable/disable the feature

Implementation Details

Verbosity Control (Inspired by Agent Vibes TTS)

The system now supports multiple verbosity levels for fine-grained control over notifications:

  1. Off: No audio notifications
  2. Minimal: Only critical events (errors, fatal issues, major completions like builds and tests)
  3. Normal: All standard status messages (default behavior)
  4. Verbose: Extended pattern matching for comprehensive coverage

This approach is inspired by Agent Vibes TTS, which pioneered selective audio notifications with configurable verbosity in Claude Code environments.

Pattern Matching

The system uses regular expressions to detect status messages in terminal output:

  • Code Review: code review completed, review completed
  • Build Status: build succeeded, build successful
  • Test Results: test passed, tests passed
  • Deployment: deployment successful, deployment complete
  • Approval Requests: approval required, waiting for approval, ready for review
  • Merge Operations: merge completed, successfully merged
  • General Completion: operation completed

All patterns are case-insensitive to catch variations in output formatting.

Anti-Spam Measures

  1. Cooldown Timer: 3-second delay between notifications prevents rapid-fire sounds
  2. Buffer Management: Only keeps the last 500 characters of terminal output to avoid excessive memory usage
  3. Settings Check: Respects both global sound settings and notification-specific settings

Audio Selection

Notification sounds are pseudo-randomly selected from a pool of available sound effects:

  • ui_hacking_charenter_01.wav
  • ui_hacking_charenter_02.wav
  • ui_hacking_charenter_03.wav
  • poweron.mp3

The getRandom() function ensures consecutive notifications don't use the same sound.

Integration Points

  1. Terminal Output Stream: Intercepts the term.write() method to monitor terminal output
  2. Settings Menu: Adds menu option under Plugins to toggle notifications
  3. Global Settings: Maintains state via global.settings.notificationsEnabled
  4. Proper Cleanup: Restores original write method on component unmount to prevent memory leaks

Note: The Hyper terminal integration is currently broken due to xterm.js migration. The primary focus is now on Claude Code plugin support.

Usage

For Users

  1. Install the plugin as documented in README.md
  2. For Hyper terminal (legacy): Access menu Plugins > Status notification sounds
  3. For Claude Code: Configure via .claude-plugin/config.json
  4. Run commands that produce status messages to hear notifications

For Developers

The system can be extended by:

  1. Adding more patterns to STATUS_PATTERNS array
  2. Adding custom sound files to the sounds/ directory
  3. Adjusting NOTIFICATION_COOLDOWN for different timing
  4. Modifying buffer size (currently 500 chars) for different detection ranges

Testing

Pattern matching is tested with a variety of messages to ensure:

  • True positives: Status messages trigger notifications
  • True negatives: Regular output doesn't trigger notifications
  • Case insensitivity: Patterns match regardless of case

Future Enhancements

Possible improvements:

  1. Configurable patterns via settings
  2. Different sound sets for different event types
  3. Adjustable cooldown period
  4. Volume control for notifications separately from typing sounds
  5. Custom sound file support