@delorenj/claude-notifications 2.0.0 → 2.1.0

package/LAYOUT-INTEGRATION.md

@@ -0,0 +1,191 @@
+# Layout Integration Fix
+
+## Issues Addressed
+
+### 1. Plugin Not Integrated Into Custom Layout
+**Problem**: The visual notifications plugin was only available in the test layout (`test-notification-plugin.kdl`), not in your actual agent-orchestrator layout.
+
+**Solution**: Integrated the plugin into `~/.config/zellij/layouts/agent-orchestrator.kdl` by adding it as a 1-line borderless pane in the `default_tab_template`. This means the plugin will be available on all tabs.
+
+### 2. All Notifications Showing Green
+**Problem**: All notification types (success, error, warning, info) were appearing in the same green color.
+
+**Root Cause**: The test layout was using the "catppuccin" theme for the plugin, but your Zellij config uses "gruvbox material dark". The theme mismatch was causing the plugin to fall back to default foreground colors.
+
+**Solution**: Updated the plugin configuration to use `theme "gruvbox-dark"` which provides proper color mappings:
+- Success: Bright green (#b8bb26)
+- Error: Bright red (#fb4934)
+- Warning: Bright yellow (#fabd2f)
+- Info: Blue (#83a598)
+- Progress: Pink/magenta (#d3869b)
+- Attention: Yellow (#fabd2f)
+
+## How to Use
+
+### Step 1: Restart Zellij with Updated Layout
+
+If you're currently in a Zellij session, you need to restart it to load the updated layout:
+
+```bash
+# Exit current Zellij session
+# Press Ctrl+Q or type 'exit' in all panes
+
+# Start Zellij with your updated layout
+zellij --layout ~/.config/zellij/layouts/agent-orchestrator.kdl
+
+# Or if agent-orchestrator is your default layout in config:
+zellij
+```
+
+### Step 2: Test Color Differentiation
+
+Run the test script to verify colors are working:
+
+```bash
+cd ~/code/utils/claude-notifications
+./test-updated-layout.sh
+```
+
+This will send one notification of each type, clearly labeled with the expected color. You should see:
+- Green notification
+- Red notification
+- Yellow notification
+- Blue notification
+- Pink/magenta notification
+
+### Step 3: Use Normally
+
+Once verified, use `zellij-notify` as normal:
+
+```bash
+# Success notification (green)
+zellij-notify -t success "Tests passed!"
+
+# Error notification (red)
+zellij-notify -t error "Build failed!"
+
+# Warning notification (yellow)
+zellij-notify -t warning "Deprecated API in use"
+
+# Info notification (blue)
+zellij-notify -t info "Deployment started"
+```
+
+## Layout Structure
+
+The updated layout now has this structure for each tab:
+
+```
+┌─────────────────────────────────┐
+│      Tab Bar (zellij)           │  ← Line 1
+├─────────────────────────────────┤
+│   Visual Notifications Plugin   │  ← Line 2 (NEW!)
+├─────────────────────────────────┤
+│                                 │
+│      Your Tab Content           │
+│      (terminals, etc.)          │
+│                                 │
+├─────────────────────────────────┤
+│     Status Bar (zellij)         │  ← Bottom 2 lines
+└─────────────────────────────────┘
+```
+
+The visual notifications plugin takes up 1 line at the top (below the tab bar), displaying active notifications with proper colors and animations.
+
+## Troubleshooting
+
+### Still Seeing All Green?
+
+1. **Make sure you restarted Zellij** - The layout needs to be reloaded
+2. **Check the plugin is loaded**:
+   ```bash
+   zellij pipe -p zellij_visual_notifications -- '{"type":"info","message":"test"}'
+   ```
+   If you get "no pipe found", the plugin isn't loaded
+
+3. **Verify the plugin file exists**:
+   ```bash
+   ls -lh ~/.config/zellij/plugins/zellij_visual_notifications.wasm
+   ```
+
+4. **Check Zellij logs**:
+   ```bash
+   tail -f /tmp/zellij-$(id -u)/zellij-log/zellij.log
+   ```
+
+### Timeout Errors
+
+If you're still seeing timeout errors on some notifications:
+
+1. **Check if it's tab-switching related**: Timeout errors often occur when trying to send to a tab that doesn't exist or when switching tabs rapidly
+2. **Try increasing timeout** in `lib/zellij.js` (currently 5 seconds)
+3. **Send to current tab only**: Omit `-i` and `-n` flags to avoid tab switching
+
+### Plugin Not Loading
+
+If the plugin doesn't load at all:
+
+1. **Rebuild the plugin**:
+   ```bash
+   cd ~/code/utils/claude-notifications/zellij-plugin
+   ./build.sh
+   ```
+
+2. **Verify plugin permissions**:
+   ```bash
+   chmod 644 ~/.config/zellij/plugins/zellij_visual_notifications.wasm
+   ```
+
+## Theme Customization
+
+If you want to use a different theme or customize colors, you can edit the plugin configuration in your layout file (`~/.config/zellij/layouts/agent-orchestrator.kdl`):
+
+### Available Themes:
+- `gruvbox-dark` (your current theme)
+- `gruvbox-light`
+- `catppuccin` / `catppuccin-mocha`
+- `catppuccin-latte`
+- `dracula`
+- `nord`
+- `solarized-dark`
+- `solarized-light`
+- `tokyo-night`
+- `one-dark`
+
+### Custom Colors:
+
+You can also override individual colors:
+
+```kdl
+plugin location="file:/home/delorenj/.config/zellij/plugins/zellij_visual_notifications.wasm" {
+    enabled "true"
+    theme "gruvbox-dark"
+    // Override individual colors:
+    success_color "#00ff00"
+    error_color "#ff0000"
+    warning_color "#ffaa00"
+    info_color "#0099ff"
+}
+```
+
+## Integration with Claude Notifications
+
+The `claude-notifications` system will automatically use visual notifications when:
+1. You're in a Zellij session
+2. The plugin is loaded
+3. `zellijVisualization.enabled` is `true` in your config
+
+Both audio and visual notifications will fire by default. To disable audio and only use visual:
+
+```json
+{
+  "sound": {
+    "enabled": false
+  },
+  "zellijVisualization": {
+    "enabled": true
+  }
+}
+```
+
+Save this to `~/.config/claude-code/settings.json`.

package/QUICK-REFERENCE.md

@@ -0,0 +1,195 @@
+# zellij-notify Quick Reference Card
+
+## Common Commands
+
+```bash
+# Basic notification
+zellij-notify "Message"
+
+# With type and priority
+zellij-notify -t TYPE -p PRIORITY "Message"
+
+# Quick 5-second notification
+zellij-notify -q "Message"
+
+# Dismissable (stays until Ctrl+N)
+zellij-notify -d "Message"
+
+# Custom TTL (seconds)
+zellij-notify --ttl 30 "Message"
+
+# To specific tab
+zellij-notify -i 2 "Message"           # By index (1-based)
+zellij-notify -n "Backend" "Message"   # By name
+
+# To all tabs
+zellij-notify -a "Message"
+
+# List tabs
+zellij-notify --list-tabs
+```
+
+## Notification Types
+
+| Flag | Type | Color | Use For |
+|------|------|-------|---------|
+| `-t success` | Success | 🟢 Green | Completed tasks, tests passed |
+| `-t error` | Error | 🔴 Red | Failures, errors |
+| `-t warning` | Warning | 🟡 Yellow | Warnings, deprecations |
+| `-t info` | Info | 🔵 Blue | General updates (default) |
+| `-t attention` | Attention | 🟣 Purple | Needs your attention |
+| `-t progress` | Progress | 🔷 Cyan | Long-running tasks |
+
+## Priority Levels
+
+| Flag | Priority | Effect |
+|------|----------|--------|
+| `-p low` | Low | Subtle, background |
+| `-p normal` | Normal | Standard (default) |
+| `-p high` | High | Prominent, demands attention |
+| `-p critical` | Critical | Urgent, highest priority |
+
+## Duration Options
+
+| Flag | Duration | Use Case |
+|------|----------|----------|
+| `--ttl 5` | 5 seconds | Quick updates |
+| `--ttl 30` | 30 seconds | Progress updates |
+| `-q` | 5 seconds | Shorthand for quick |
+| (default) | 300 seconds | Standard notifications |
+| `-d` | Until Ctrl+N | Requires acknowledgment |
+
+## Common Patterns
+
+### Build Notifications
+```bash
+# Start
+zellij-notify -t progress -q "Building..."
+
+# Success
+zellij-notify -t success "Build complete"
+
+# Failure
+zellij-notify -d -t error "Build failed"
+```
+
+### Test Results
+```bash
+# Running
+zellij-notify -t progress "Running tests..."
+
+# Passed
+zellij-notify -t success "Tests passed ✅"
+
+# Failed
+zellij-notify -d -t error "Tests failed ❌"
+```
+
+### Deployment
+```bash
+# Starting
+zellij-notify -a -t info "Deployment started"
+
+# Complete
+zellij-notify -a -t success -p high "Deployed! 🚀"
+
+# Failure
+zellij-notify -a -d -t error -p critical "Deployment failed!"
+```
+
+### Long Tasks
+```bash
+# Start
+zellij-notify -t progress "Processing..."
+
+# Complete (requires review)
+zellij-notify -d -t attention "Review required"
+```
+
+## Script Integration
+
+```bash
+#!/bin/bash
+# build.sh
+
+zellij-notify -t info "Building..."
+
+if make build; then
+  zellij-notify -t success "Build complete"
+else
+  zellij-notify -d -t error "Build failed"
+  exit 1
+fi
+```
+
+## Chaining
+
+```bash
+# Success chain
+zellij-notify -q "Starting..." && \
+  long_task && \
+  zellij-notify -t success "Done!"
+
+# With failure handling
+zellij-notify -q "Starting..." && \
+  risky_task && \
+  zellij-notify -t success "Success" || \
+  zellij-notify -t error "Failed"
+```
+
+## Tab Management
+
+```bash
+# List tabs first
+zellij-notify --list-tabs
+
+# Target specific tabs
+zellij-notify -i 1 "For tab 1"
+zellij-notify -i 2 "For tab 2"
+zellij-notify -n "Backend" "For backend tab"
+
+# Broadcast
+zellij-notify -a "For everyone"
+```
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `Ctrl+N` | Clear all notifications in current tab |
+
+## Full Help
+
+```bash
+zellij-notify --help
+```
+
+## Documentation
+
+- [Full CLI Documentation](./ZELLIJ-NOTIFY.md)
+- [Integration Guide](./INTEGRATION.md)
+- [Examples](./examples/zellij-notify-examples.sh)
+
+---
+
+**Quick Copy-Paste Templates:**
+
+```bash
+# Success
+zellij-notify -t success "Task complete"
+
+# Error (dismissable)
+zellij-notify -d -t error "Critical error"
+
+# Warning with 30s TTL
+zellij-notify -t warning --ttl 30 "Warning message"
+
+# Info to all tabs
+zellij-notify -a -t info "System update"
+
+# Attention to specific tab
+zellij-notify -i 2 -t attention "Review needed"
+
+# Quick progress update
+zellij-notify -q -t progress "Processing..."
+```

package/README.md

@@ -8,14 +8,17 @@ Delightful audible notifications for Claude Code. Never alt+tab back to disappoi
 
 ```bash
 npm install -g @delorenj/claude-notifications
+claude-notifications install
 ```
 
-That's it! 🎉 The package will automatically:
+Step 1 installs the CLI and generates sound assets. Step 2 opens an interactive selector that:
+
+- 🔎 Detects every supported agent CLI on your `$PATH` (Claude Code, Opencode, Gemini, Auggie, Copilot, Kimi, Vibe, Codex)
+- ☑️ Lets you toggle which ones should receive notification hooks
+- 🪝 Writes a marker-tagged hook block into each selected CLI's config (idempotent — re-running is safe)
+- 🚫 Shows unsupported CLIs disabled with a reason rather than silently skipping them
 
-- ✅ Install the notification system
-- 🎼 Generate a delightful notification scale
-- 🪝 Configure Claude Code stop hooks
-- 🧪 Test the installation
+Hook installation no longer runs automatically on `npm install` — it's an explicit, opt-in step so you stay in control of what gets written to your agent configs.
 
 ## Features
 
@@ -23,9 +26,10 @@ That's it! 🎉 The package will automatically:
 - 🔔 **Service Desk Bell** - Optional short, crisp bell sound for a quick "done!" signal
 - 🔊 **Cross-Platform Audio** - Works on Linux and macOS
 - 🖥️ **Desktop Notifications** - Visual notifications with Claude Code branding (optional)
+- 🎨 **Zellij Visual Notifications** - Beautiful animated pane borders and status bar notifications
 - 🪝 **Auto-Integration** - Automatically configures Claude Code hooks
 - ⚡ **Zero Configuration** - Works out of the box
--  webhook **Webhook Support** - Trigger a webhook in addition to or instead of the sound
+- 🌐 **Webhook Support** - Trigger a webhook in addition to or instead of the sound
 - 🎨 **Customizable** - Easy to modify sounds and settings
 
 ## Usage
@@ -35,25 +39,89 @@ After installation, Claude Code will begin notifying you when it finishes or is
 ### Manual Commands
 
 ```bash
+# Interactive hook installer (TUI)
+claude-notifications install
+
+# Scripted install for specific CLIs (skips the TUI)
+claude-notifications install --non-interactive --cli=claude-code
+
+# Preview changes without writing
+claude-notifications install --dry-run --cli=claude-code
+
+# Show which CLIs are detected and whether hooks are installed
+claude-notifications status
+claude-notifications status --json
+
+# Cleanly remove everything this package installed
+claude-notifications uninstall
+
+# Regenerate sound assets only
+claude-notifications sounds
+
 # Trigger notification manually
 claude-notify
-
-# Trigger bell notification manually
 claude-notify --bell
 
 # Test the system
 claude-notifications test
-
-# Test the bell sound
 claude-notifications test-bell
 
-# Reinstall/repair
-claude-notifications install
-
-# Get help
+# Full flag reference
 claude-notifications help
 ```
 
+### Adding support for another agent CLI
+
+Each supported CLI is a module under `lib/adapters/<id>.js` exporting this shape:
+
+```js
+{
+  id, label, binary, supportsHooks,
+  detect(deps), configPath(), install(ctx), uninstall(ctx), status(ctx)
+}
+```
+
+To add a new adapter:
+
+1. Copy `lib/adapters/claude-code.js` as a starting point (for hook-capable CLIs)
+   or `lib/adapters/_stub.js::createStubAdapter({...})` (for CLIs whose hook API
+   you haven't verified yet).
+2. Implement `install` / `uninstall` using the `upsertByMarker` / `removeByMarker`
+   helpers from `lib/adapters/index.js` so the entry is idempotent and cleanly
+   removable.
+3. Register the module by appending a `require()` line to the `adapterFactories`
+   array in `lib/adapters/index.js`.
+4. Add a test under `test/adapters/<id>.test.js` following the pattern in
+   `test/adapters/claude-code.test.js`.
+
+The TUI and status commands pick up the new adapter automatically.
+
+### Zellij CLI
+
+The package also includes `zellij-notify` for programmatic control:
+
+```bash
+# Send notification to current tab
+zellij-notify "Build complete!"
+
+# Send to specific tab by index
+zellij-notify -i 2 "Backend tests passed"
+
+# Quick 5-second notification
+zellij-notify -q "Deployment started"
+
+# Dismissable alert (requires Ctrl+N to clear)
+zellij-notify -d -t error "Review required"
+
+# Broadcast to all tabs
+zellij-notify -a "System maintenance in 5 minutes"
+
+# Full help
+zellij-notify --help
+```
+
+See [ZELLIJ-NOTIFY.md](./ZELLIJ-NOTIFY.md) for complete CLI documentation.
+
 ## The Sound
 
 - **Pattern**: C1-D1-E1-G1-C2-D2-E2-G2-C3-G2-E2-D2-C2-G1-E1-D1-C1
@@ -117,6 +185,63 @@ ls ~/.local/share/sounds/claude-notification.wav
 cp your-custom-sound.wav ~/.local/share/sounds/claude-notification.wav
 ```
 
+### Zellij Visual Notifications
+
+If you're using [Zellij](https://zellij.dev/) as your terminal multiplexer, `claude-notifications` can send visual notifications directly to your Zellij panes with animated borders, status bar indicators, and tab badges.
+
+**Setup:**
+
+1. **Install the Zellij plugin:**
+   ```bash
+   # The plugin should be installed at:
+   ~/.config/zellij/plugins/zellij_visual_notifications.wasm
+   ```
+
+2. **Add to your Zellij layout:**
+   ```kdl
+   layout {
+       pane
+       pane size=1 {
+           plugin location="file:~/.config/zellij/plugins/zellij_visual_notifications.wasm" {
+               enabled true
+               theme "catppuccin"  // or dracula, nord, tokyo-night, etc.
+               show_status_bar true
+               show_border_colors true
+               animation_enabled true
+           }
+       }
+   }
+   ```
+
+3. **Configure in settings.json:**
+   ```json
+   {
+     "zellijVisualization": {
+       "enabled": true,
+       "pluginName": "zellij_visual_notifications",
+       "notificationType": "attention",
+       "title": "Claude Code",
+       "message": "Waiting for you...",
+       "priority": "high"
+     }
+   }
+   ```
+
+**Visual Features:**
+- 🎨 **Animated Pane Borders** - Pulsing colors based on notification type
+- 📊 **Status Bar Widget** - Shows active notifications with icons
+- 🏷️ **Tab Badges** - Visual indicators on tabs with active notifications
+- ⌨️ **Keyboard Control** - Press `Ctrl+N` to clear notifications
+- 🎭 **10+ Themes** - Catppuccin, Dracula, Nord, Tokyo Night, and more
+- ♿ **Accessibility** - Pattern-based indicators for color-blind users
+
+**Notification Types:**
+- ✅ `success` - Green pulsing border (build passed, tests succeeded)
+- ❌ `error` - Red pulsing border (build failed, errors found)
+- ⚠️ `warning` - Yellow pulsing border (warnings, deprecated APIs)
+- ℹ️ `info` - Blue pulsing border (general information)
+- 👁️ `attention` - Purple pulsing border (Claude waiting for input)
+
 ### Configure Webhooks
 
 You can configure a webhook to be triggered when a notification occurs. This is useful for integrating with other services, such as IFTTT, Zapier, or a custom server.
@@ -145,6 +270,12 @@ Create a configuration file at `~/.config/claude-notifications/settings.json`.
   - `"claude-notification"` - Final Fantasy dream harp (default)
   - `"claude-notification-bell"` - Service desk bell
 - `desktopNotification`: (boolean) Whether to show desktop notification banners. Defaults to `false`.
+- `zellijVisualization.enabled`: (boolean) Whether to send visual notifications to Zellij. Defaults to `true` when inside Zellij.
+- `zellijVisualization.pluginName`: (string) Name of the Zellij plugin to send notifications to. Defaults to `"zellij_visual_notifications"`.
+- `zellijVisualization.notificationType`: (string) Type of notification to send. Options: `success`, `error`, `warning`, `info`, `attention`, `progress`. Defaults to `"attention"`.
+- `zellijVisualization.title`: (string) Notification title. Defaults to `"Claude Code"`.
+- `zellijVisualization.message`: (string) Notification message. Defaults to `"Waiting for you..."`.
+- `zellijVisualization.priority`: (string) Notification priority. Options: `low`, `normal`, `high`, `critical`. Defaults to `"high"`.
 - `webhook.enabled`: (boolean) Whether to trigger the webhook. Defaults to `false`.
 - `webhook.url`: (string) The URL to send the POST request to.
 - `webhook.replaceSound`: (boolean) If `true`, the sound will not play when a webhook is triggered. Defaults to `false`.

package/TASK.md

@@ -0,0 +1,15 @@
+# Zellij Visual Integration
+
+Now hear me out...
+I LOVE this notification. It works really really well.
+But I want to explore a new possibility -
+
+## Goal
+
+For every notification, i would like a visual cue to accompany it.
+
+## Requirements
+
+1. The visual cue should be associated with the Zellij tab in your active session that the notification was meant for.
+2. The notification should remain visible until acknowledged by visiting the tab by making it active
+3. The notification should include periodic movement (a bounce, spin, arrow, etc) to draw attention every 30 seconds.