huesignal 💡

Visual feedback for AI agents and automation workflows.

Turn your Philips Hue lights into a status dashboard. Perfect for coding agents to signal task progress, CI/CD pipelines to show build status, and developers who want ambient feedback without context-switching.

# Green pulse = task complete
huesignal effect apply pulse -l desk-light -c green -b 0.7

# Red blinks = error/blocker  
huesignal effect apply blink -l desk-light -c red --count 3

⚡ 60-Second Quickstart

# Install
uv pip install huesignal       # or: pip install huesignal

# Interactive setup wizard (recommended for first-time users)
huesignal --getting-started

# Or manual setup:
huesignal auth login           # Press bridge link button when prompted
huesignal lights list          # Discover your lights

# Try a preset or demo
huesignal effect preset success -l "your-light-name"
huesignal effect demo --quick   # See all effects in action

🎯 Why huesignal?

📦 Installation

Using uv (Recommended)

uv pip install huesignal

From Source

git clone https://github.com/ThomasRohde/huesignal.git
cd huesignal
uv sync
uv run huesignal --version

Using pip/pipx

pip install huesignal     # or: pipx install huesignal

🎨 Effects Reference

Quick Presets (New!)

For common workflow scenarios, use semantic presets:

huesignal effect preset success   # Task completed (green pulse)
huesignal effect preset error     # Error encountered (red blink x3)
huesignal effect preset working   # In progress (blue breathe)
huesignal effect preset claim     # Task claimed (blue pulse)
huesignal effect preset blocker   # Critical issue (red blink x5)

Available presets: success, error, warning, working, complete, claim, verify, blocker

Demo Mode

See all effects in action:

huesignal effect demo -l desk-light    # Full demo (~2 minutes)
huesignal effect demo --quick          # Quick demo (~30 seconds)

Available Effects

Brightness Formats (Now Consistent!)

All brightness values accept three formats everywhere (CLI and YAML):

• Decimal: 0.0-1.0 (e.g., 0.75 = 75% brightness)
• Percentage: 0-100 (e.g., 75 = 75% brightness)
• Raw: 1-254 (Hue API values)

# All three are equivalent:
huesignal effect apply pulse -b 0.8   # Decimal
huesignal effect apply pulse -b 80    # Percentage
huesignal effect apply pulse -b 203   # Raw API value

Common Options

Colors

Named colors: red, green, blue, yellow, orange, purple, pink, cyan, white, magenta

Semantic colors: success (green), error (red), warning (orange), info (blue), working (light blue), celebration (gold)

Semantic colors: success (green), error (red), warning (orange), info (blue), working (sky blue), celebration (gold)

Hex codes: #FF0000, #00FF00, #0000FF, etc.

Brightness Formats

-b 75       # Percentage (0-100)
-b 0.75     # Decimal (0.0-1.0)  
-b 191      # Raw Hue value (1-254)

🤖 Agent Workflow Patterns

Perfect for AI coding agents to provide visual status:

# Task claimed - blue pulse
huesignal effect apply pulse -c blue -b 0.5 2>/dev/null || true

# Task complete - green pulse
huesignal effect apply pulse -c green -b 0.7 2>/dev/null || true

# Error/blocker - red blinks
huesignal effect apply blink -c red --count 3 -b 1.0 2>/dev/null || true

# Working/thinking - slow breathe
huesignal effect apply breathe -c working -d 3000 2>/dev/null || true

# Celebration - rainbow!
huesignal effect apply rainbow -d 5000 2>/dev/null || true

Tip: Append 2>/dev/null || true in scripts to gracefully handle missing bridge/lights.

Environment Variable

Set a default light to avoid -l on every command:

export HUESIGNAL_LIGHT_NAME="desk-light"
huesignal effect apply pulse -c green    # Uses desk-light automatically

🎼 YAML Programs (Symphony of Lights)

Create choreographed multi-light sequences with YAML programs.

Quick Start

# Run a program
huesignal run examples/celebration.yaml

# Validate without executing
huesignal run my-program.yaml --validate

# Preview timing (requires bridge)
huesignal run my-program.yaml --dry-run

YAML Schema

name: program-name              # Required: Unique identifier
description: What this does     # Optional: Human-readable description

tracks:                         # Required: List of light tracks
  - light: "light-name"         # Required: Light name or pattern (supports *)
    steps:                      # Required: Sequence of actions
      
      # Effect step - apply a visual effect
      - effect: pulse           # Effect name: pulse, blink, breathe, rainbow
        options:                # Optional: Effect-specific options
          color: green
          brightness: 200
          count: 2
        duration_ms: 1500       # Step duration in milliseconds
      
      # Wait step - pause the timeline
      - wait: 500               # Pause in milliseconds
      
      # Set step - direct state change
      - set:
          on: true              # Power state
          brightness: 150       # 1-254
          color: "#FF6600"      # Hex, name, or [x, y] tuple
          transition_ms: 300    # Fade duration

      # Parallel execution - use start_ms for absolute positioning
      - start_ms: 0             # Starts at time 0
        effect: pulse
        duration_ms: 2000
      - start_ms: 0             # Also starts at 0 - runs in parallel!
        effect: breathe
        duration_ms: 2000

Parallel Execution

By default, steps run sequentially. Use start_ms to specify absolute start times for parallel execution:

steps:
  # These run in parallel (both start at 0ms)
  - start_ms: 0
    effect: pulse
    options: { color: blue, count: 3 }
    duration_ms: 3000
  - start_ms: 0
    effect: breathe
    options: { color: cyan }
    duration_ms: 3000
  
  # This runs after (starts at 3000ms)
  - start_ms: 3000
    effect: rainbow
    duration_ms: 2000

Example: Celebration Sequence

name: celebration
description: Victory dance for completed milestones

tracks:
  - light: desk-light
    steps:
      - effect: pulse
        options:
          color: success
          count: 3
        duration_ms: 2000
      - wait: 200
      - effect: rainbow
        duration_ms: 4000

  - light: ambient-light
    steps:
      - wait: 500
      - effect: breathe
        options:
          color: celebration
        duration_ms: 5000

See the examples/ directory for more programs.

📋 Command Reference

Authentication

huesignal auth login                    # Pair with bridge (stores credentials)
huesignal auth login --bridge-ip 192.168.1.100  # Specify bridge IP

Lights

huesignal lights list                   # Show all lights with status
huesignal lights list --filter desk     # Filter by name
huesignal lights show <name>            # Detailed light info
huesignal lights on <name>              # Turn on
huesignal lights on <name> -b 50        # Turn on at 50% brightness
huesignal lights off <name>             # Turn off

Effects

huesignal effect list                   # Show available effects
huesignal effect params <name>          # Show effect parameters
huesignal effect apply <name> [options] # Apply effect
huesignal effect play <file.yaml>       # Run YAML program

Programs (Shorthand)

huesignal run <file.yaml>               # Execute YAML program
huesignal run <file.yaml> --validate    # Validate only (no bridge needed)
huesignal run <file.yaml> --dry-run     # Preview without execution

Samples

huesignal samples list                  # List automation templates
huesignal samples show <name>           # Display a sample

Utilities

huesignal doctor                        # Diagnostic checks
huesignal doctor --verbose              # Detailed diagnostics
huesignal cache clear                   # Clear cached data
huesignal --explain                     # Comprehensive usage examples

🧪 Testing

Unit Tests

pytest tests/                           # Mocked, no bridge required

Integration Tests

export HUESIGNAL_BRIDGE_IP="192.168.1.100"
export HUESIGNAL_APP_KEY="your-app-key"
pytest tests/integration/               # Requires real bridge

⚠️ Integration tests modify light state. Only run against your own bridge.

🔧 Configuration

Environment Variables

Credential Storage

Credentials are stored securely in Windows Credential Manager (or system keyring on macOS/Linux).

📚 More Resources

• EFFECTS_PRD.md — Technical specification for the effect programming model
• CONTRIBUTING.md — Contribution guidelines
• AGENTS.md — Multi-agent coordination with Lodestar

🏗️ Architecture

huesignal uses aiohue for async bridge communication:

• Full Hue API v2 support — Latest bridge features
• Async/await — Non-blocking for responsive CLI
• Battle-tested — Powers Home Assistant

📄 License

MIT — see LICENSE

Make your lights dance. 💡✨