@delorenj/claude-notifications 2.0.0 → 2.1.0

package/zellij-plugin/docs/CONFIGURATION.md

@@ -0,0 +1,191 @@
+# Configuration Reference
+
+Complete reference for all configuration options in Zellij Visual Notifications.
+
+## Configuration Location
+
+The plugin is configured within your Zellij configuration file:
+
+- `~/.config/zellij/config.kdl`
+
+## Options Reference
+
+### General Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `true` | Enable/disable the plugin |
+| `debug` | boolean | `false` | Enable debug logging |
+
+### Theme Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `theme` | string | `"default"` | Theme preset name |
+| `success_color` | string | Theme-dependent | Color for success notifications (hex) |
+| `error_color` | string | Theme-dependent | Color for error notifications (hex) |
+| `warning_color` | string | Theme-dependent | Color for warning notifications (hex) |
+| `info_color` | string | Theme-dependent | Color for info notifications (hex) |
+
+#### Available Themes
+
+- `default` - Default color scheme
+- `dracula` - Dracula theme colors
+- `nord` - Nord theme colors
+- `catppuccin` or `catppuccin-mocha` - Catppuccin Mocha (dark)
+- `catppuccin-latte` - Catppuccin Latte (light)
+- `gruvbox` or `gruvbox-dark` - Gruvbox Dark
+- `gruvbox-light` - Gruvbox Light
+- `tokyo-night` - Tokyo Night colors
+- `one-dark` - One Dark colors
+- `solarized` or `solarized-dark` - Solarized Dark
+- `solarized-light` - Solarized Light
+
+### Animation Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `animation_enabled` | boolean | `true` | Enable/disable animations |
+| `animation_style` | string | `"pulse"` | Animation style |
+| `animation_speed` | integer | `50` | Animation speed (1-100) |
+| `animation_cycles` | integer | `3` | Number of animation cycles |
+
+#### Animation Styles
+
+- `pulse` - Smooth fade in/out using sine wave
+- `flash` - Quick on/off blink
+- `fade` - Gradual fade out over animation duration
+- `breathe` - Smooth breathing effect
+- `none` - No animation (static color)
+
+### Display Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `show_status_bar` | boolean | `true` | Show status bar widget |
+| `show_border_colors` | boolean | `true` | Show border colors on panes |
+| `show_tab_badges` | boolean | `true` | Show badges on pane tabs |
+
+### Notification Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `notification_timeout_ms` | integer | `300000` | Notification TTL in milliseconds (5 min) |
+| `queue_max_size` | integer | `100` | Maximum notifications in queue |
+
+### Accessibility Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `high_contrast` | boolean | `false` | Enable high contrast mode |
+| `reduced_motion` | boolean | `false` | Disable all animations |
+
+## Examples
+
+### Basic Configuration
+
+```kdl
+plugins {
+    visual-notifications location="file:~/.config/zellij/plugins/zellij-visual-notifications.wasm" {
+        enabled true
+        theme "dracula"
+    }
+}
+```
+
+### Custom Colors
+
+```kdl
+plugins {
+    visual-notifications location="file:~/.config/zellij/plugins/zellij-visual-notifications.wasm" {
+        enabled true
+        theme "default"
+
+        // Override specific colors
+        success_color "#50fa7b"
+        error_color "#ff5555"
+        warning_color "#f1fa8c"
+        info_color "#8be9fd"
+    }
+}
+```
+
+### Animation Configuration
+
+```kdl
+plugins {
+    visual-notifications location="file:~/.config/zellij/plugins/zellij-visual-notifications.wasm" {
+        enabled true
+
+        // Fast, attention-grabbing animation
+        animation_enabled true
+        animation_style "flash"
+        animation_speed 80
+        animation_cycles 5
+    }
+}
+```
+
+### Minimal Distraction
+
+```kdl
+plugins {
+    visual-notifications location="file:~/.config/zellij/plugins/zellij-visual-notifications.wasm" {
+        enabled true
+
+        // Only border colors, no animation
+        animation_enabled false
+        show_status_bar false
+        show_tab_badges false
+        show_border_colors true
+
+        // Quick timeout
+        notification_timeout_ms 30000
+    }
+}
+```
+
+### Accessibility Configuration
+
+```kdl
+plugins {
+    visual-notifications location="file:~/.config/zellij/plugins/zellij-visual-notifications.wasm" {
+        enabled true
+
+        // Accessibility features
+        high_contrast true
+        reduced_motion true
+
+        // Longer timeout
+        notification_timeout_ms 600000
+    }
+}
+```
+
+## Environment Variables
+
+The plugin respects these environment variables (when detectable):
+
+| Variable | Effect |
+|----------|--------|
+| `COLORTERM` | Detects true color support |
+| `TERM` | Detects terminal color capabilities |
+
+## Hot Reload
+
+Configuration changes require reloading the plugin:
+
+1. Save your config file
+2. Restart Zellij, or
+3. Reload the plugin via keybinding
+
+## Validation
+
+The plugin validates configuration on load:
+
+- Invalid color values fall back to theme defaults
+- Invalid animation speeds are clamped to 1-100
+- Invalid animation cycles are clamped to 1-10
+- Unknown themes fall back to default
+
+Validation errors are logged to Zellij's log file.

package/zellij-plugin/docs/INTEGRATION.md

@@ -0,0 +1,333 @@
+# Integration Guide
+
+How to integrate Zellij Visual Notifications with claude-notifications and other systems.
+
+## Integration with claude-notifications
+
+The primary use case for this plugin is integration with the claude-notifications npm package.
+
+### Setup
+
+1. Install claude-notifications globally:
+
+```bash
+npm install -g @delorenj/claude-notifications
+```
+
+2. Install the Zellij plugin (see README)
+
+3. Configure claude-notifications to send messages to the plugin
+
+### Modifying claude-notify.js
+
+Add Zellij integration to the notification trigger (`bin/claude-notify.js`):
+
+```javascript
+const { execSync } = require('child_process');
+
+function notifyZellij(type, message) {
+    // Check if we're in a Zellij session
+    if (!process.env.ZELLIJ) {
+        return;
+    }
+
+    const payload = JSON.stringify({
+        type: type,
+        message: message,
+        source: 'claude-notifications',
+        timestamp: Date.now()
+    });
+
+    try {
+        // Send via Zellij pipe
+        execSync(`echo '${payload}' | zellij pipe -p visual-notifications`, {
+            stdio: 'ignore'
+        });
+    } catch (e) {
+        // Zellij notification failed, continue silently
+    }
+}
+
+// In the main notification function:
+function main() {
+    // ... existing notification logic ...
+
+    // Add Zellij visual notification
+    notifyZellij('attention', 'Claude is waiting for you...');
+}
+```
+
+## Message Protocol
+
+### Request Format
+
+Send JSON messages to the plugin via Zellij pipe:
+
+```bash
+echo '{"type":"success","message":"Build completed"}' | zellij pipe -p visual-notifications
+```
+
+### Full Message Schema
+
+```typescript
+interface NotificationMessage {
+    // Required
+    message: string;
+
+    // Optional
+    version?: string;           // Protocol version (default: "1.0")
+    type?: string;              // success|error|warning|info|attention|progress
+    title?: string;             // Notification title
+    source?: string;            // Source identifier
+    pane_id?: number;           // Target pane ID
+    tab_index?: number;         // Target tab index
+    priority?: string;          // low|normal|high|critical
+    timestamp?: number;         // Unix timestamp (ms)
+    ttl_ms?: number;            // Time-to-live (ms)
+    command?: string;           // Command that triggered notification
+    exit_code?: number;         // Command exit code
+    duration_ms?: number;       // Command duration (ms)
+}
+```
+
+### Response
+
+The plugin does not send responses. It processes messages asynchronously.
+
+## Command Line Integration
+
+### Manual Notifications
+
+```bash
+# Success
+zellij-notify success "Build completed successfully"
+
+# Error
+zellij-notify error "Tests failed: 3 failures"
+
+# Warning
+zellij-notify warning "Memory usage high"
+
+# Attention (Claude waiting)
+zellij-notify attention "Claude is waiting for input"
+```
+
+### Shell Function
+
+Add to your `.bashrc` or `.zshrc`:
+
+```bash
+zellij-notify() {
+    local type="$1"
+    local message="$2"
+
+    if [ -z "$ZELLIJ" ]; then
+        echo "Not in Zellij session"
+        return 1
+    fi
+
+    echo "{\"type\":\"$type\",\"message\":\"$message\"}" | zellij pipe -p visual-notifications
+}
+```
+
+### Git Hooks
+
+Add visual notifications to Git operations:
+
+```bash
+# .git/hooks/post-commit
+#!/bin/bash
+if [ -n "$ZELLIJ" ]; then
+    echo '{"type":"success","message":"Commit created"}' | zellij pipe -p visual-notifications
+fi
+```
+
+```bash
+# .git/hooks/post-merge
+#!/bin/bash
+if [ -n "$ZELLIJ" ]; then
+    echo '{"type":"info","message":"Merge completed"}' | zellij pipe -p visual-notifications
+fi
+```
+
+### Build System Integration
+
+#### npm scripts
+
+```json
+{
+    "scripts": {
+        "build": "tsc && npm run notify:success",
+        "notify:success": "[ -n \"$ZELLIJ\" ] && echo '{\"type\":\"success\",\"message\":\"Build completed\"}' | zellij pipe -p visual-notifications || true",
+        "notify:error": "[ -n \"$ZELLIJ\" ] && echo '{\"type\":\"error\",\"message\":\"Build failed\"}' | zellij pipe -p visual-notifications || true"
+    }
+}
+```
+
+#### Makefile
+
+```makefile
+.PHONY: build notify-success notify-error
+
+build:
+    cargo build --release
+    @$(MAKE) notify-success
+
+notify-success:
+    @if [ -n "$$ZELLIJ" ]; then \
+        echo '{"type":"success","message":"Build completed"}' | zellij pipe -p visual-notifications; \
+    fi
+
+notify-error:
+    @if [ -n "$$ZELLIJ" ]; then \
+        echo '{"type":"error","message":"Build failed"}' | zellij pipe -p visual-notifications; \
+    fi
+```
+
+## Programmatic Integration
+
+### Node.js
+
+```javascript
+const { execSync } = require('child_process');
+
+class ZellijNotifier {
+    static isAvailable() {
+        return !!process.env.ZELLIJ;
+    }
+
+    static notify(type, message, options = {}) {
+        if (!this.isAvailable()) return;
+
+        const payload = {
+            type,
+            message,
+            timestamp: Date.now(),
+            ...options
+        };
+
+        try {
+            execSync(`echo '${JSON.stringify(payload)}' | zellij pipe -p visual-notifications`, {
+                stdio: 'ignore'
+            });
+        } catch (e) {
+            // Silently fail
+        }
+    }
+
+    static success(message) { this.notify('success', message); }
+    static error(message) { this.notify('error', message); }
+    static warning(message) { this.notify('warning', message); }
+    static info(message) { this.notify('info', message); }
+    static attention(message) { this.notify('attention', message); }
+}
+
+module.exports = ZellijNotifier;
+```
+
+### Python
+
+```python
+import os
+import json
+import subprocess
+
+class ZellijNotifier:
+    @staticmethod
+    def is_available():
+        return 'ZELLIJ' in os.environ
+
+    @staticmethod
+    def notify(type: str, message: str, **kwargs):
+        if not ZellijNotifier.is_available():
+            return
+
+        payload = {
+            'type': type,
+            'message': message,
+            **kwargs
+        }
+
+        try:
+            subprocess.run(
+                f"echo '{json.dumps(payload)}' | zellij pipe -p visual-notifications",
+                shell=True,
+                capture_output=True
+            )
+        except Exception:
+            pass
+
+    @staticmethod
+    def success(message): ZellijNotifier.notify('success', message)
+
+    @staticmethod
+    def error(message): ZellijNotifier.notify('error', message)
+
+    @staticmethod
+    def warning(message): ZellijNotifier.notify('warning', message)
+
+    @staticmethod
+    def info(message): ZellijNotifier.notify('info', message)
+
+    @staticmethod
+    def attention(message): ZellijNotifier.notify('attention', message)
+```
+
+### Rust
+
+```rust
+use std::process::Command;
+
+pub struct ZellijNotifier;
+
+impl ZellijNotifier {
+    pub fn is_available() -> bool {
+        std::env::var("ZELLIJ").is_ok()
+    }
+
+    pub fn notify(notification_type: &str, message: &str) {
+        if !Self::is_available() {
+            return;
+        }
+
+        let payload = format!(
+            r#"{{"type":"{}","message":"{}"}}"#,
+            notification_type, message
+        );
+
+        let _ = Command::new("sh")
+            .arg("-c")
+            .arg(format!(
+                "echo '{}' | zellij pipe -p visual-notifications",
+                payload
+            ))
+            .output();
+    }
+
+    pub fn success(message: &str) { Self::notify("success", message); }
+    pub fn error(message: &str) { Self::notify("error", message); }
+    pub fn warning(message: &str) { Self::notify("warning", message); }
+    pub fn info(message: &str) { Self::notify("info", message); }
+    pub fn attention(message: &str) { Self::notify("attention", message); }
+}
+```
+
+## Troubleshooting Integration
+
+### Plugin not receiving messages
+
+1. Verify you're in a Zellij session: `echo $ZELLIJ`
+2. Check plugin is loaded: Look for the status bar widget
+3. Test with direct pipe: `echo '{"type":"info","message":"test"}' | zellij pipe -p visual-notifications`
+
+### Messages not displaying
+
+1. Check pane ID is valid (if specified)
+2. Verify JSON is valid: `echo '{"type":"info","message":"test"}' | jq .`
+3. Check notification timeout hasn't expired
+
+### Performance issues
+
+1. Reduce `queue_max_size` if memory is a concern
+2. Disable animations with `animation_enabled false`
+3. Use shorter TTL values