Configuration¶

agentwatch uses a YAML configuration file for daemon mode. The default location is ~/.config/agentwatch/config.yaml.

Generating Configuration¶

# Generate default config
agentwatch --generate-config > ~/.config/agentwatch/config.yaml

Full Configuration Reference¶

# Service settings
service:
  # Interval for discovering new tmux sessions (seconds)
  session_discovery_interval: 5

  # Interval for capturing each session (seconds)
  capture_interval: 1

  # tmux socket path (null = default socket)
  tmux_socket: null

  # Logging level: DEBUG, INFO, WARNING, ERROR
  log_level: INFO

  # Default capture dimensions
  capture_cols: 80
  capture_rows: 24

  # Debug settings
  debug:
    enabled: false
    # Directory to write capture files for debugging
    capture_dir: null
    # Auto-cleanup captures older than this (hours)
    retention_hours: 4.0
    # Log each capture to debug output
    log_captures: false
    # Log detection results
    log_detections: false
    # Log state changes (recommended)
    log_state_changes: true
    # Log hook executions
    log_hooks: true
    # Dry run mode - log but don't execute hooks
    dry_run_hooks: false

# Query API settings
api:
  unix_socket:
    enabled: true
    path: /tmp/agentwatch.sock

  http:
    enabled: false
    host: 127.0.0.1
    port: 9876

# Web viewer settings
web_viewer:
  enabled: true
  # Host to bind (0.0.0.0 for LAN access)
  host: 127.0.0.1
  port: 8081

  # Session signing secret (auto-generated if null)
  # Set explicitly to preserve sessions across restarts
  session_secret: null

  # Streaming frame rate
  fps: 2.0

  # Rate limit for input messages per second
  max_input_rate: 20

  # SSL certificate paths (optional)
  ssl_cert: null
  ssl_key: null

# Cloudflare Tunnel settings
cloudflare:
  enabled: false
  # Path to cloudflared config file
  config_file: ~/.cloudflared/config-agentwatch.yml
  # Path to cloudflared binary
  cloudflared_bin: cloudflared

# MCP server settings
mcp:
  enabled: false
  transport: stdio
  session_prefix: coding-
  max_sessions: 3
  capture_lines: 50

# Hook definitions
hooks:
  # Example: Webhook on state change
  - name: state-webhook
    type: webhook
    trigger: state_change
    # Optional: Only fire for specific programs
    programs: ["Claude Code"]
    # Optional: Only fire when entering these states
    to_states: [Error, Blocked]
    # Webhook URL
    url: "http://localhost:8080/hook"
    # What to include: status, json, text, png
    include: status

  # Example: Shell command on work completion
  - name: work-complete
    type: shell
    trigger: state_change
    from_states: [Working]
    to_states: [Idle]
    command: 'echo "Work complete in $SESSION_NAME" | mail admin@example.com'

  # Example: Error alert
  - name: error-alert
    type: shell
    trigger: state_change
    to_states: [Error]
    command: 'say "Error detected in coding session"'

Hook Configuration¶

Trigger Types¶

Trigger	Fires When
`program_change`	Program changes (e.g., shell to Claude Code)
`state_change`	State changes (Idle, Working, Blocked, Error)
`any_change`	Either program or state changes

Filters¶

Filter	Description
`programs`	Only fire for these programs (current)
`from_programs`	Only fire when leaving these programs
`to_programs`	Only fire when entering these programs
`states`	Only fire for these states (current)
`from_states`	Only fire when leaving these states
`to_states`	Only fire when entering these states

Include Formats¶

Format	Description
`status`	Lightweight JSON with program/state/detail
`json`	Full detection JSON output
`text`	Text capture (shell: temp file in `$CAPTURE_FILE`)
`png`	PNG screenshot (webhook: base64, shell: temp file)

Shell Hook Environment Variables¶

AGENT_WATCH_TRIGGER     # Trigger type
SESSION_NAME            # tmux session name
SESSION_ID              # tmux session ID
PROGRAM                 # Current program name
PROGRAM_VERSION         # Program version (if detected)
STATE                   # Current state
DETAIL                  # State detail
PREVIOUS_PROGRAM        # Previous program
PREVIOUS_STATE          # Previous state
PREVIOUS_DETAIL         # Previous detail
TIMESTAMP               # ISO timestamp
DURATION_SECONDS        # Duration in previous state
CAPTURE_FILE            # Path to capture file (if include: text or png)

Environment Variables¶

These environment variables can override configuration:

Variable	Description
`AGENT_WATCH_SOCKET`	tmux socket path
`AGENT_WATCH_TARGET`	tmux pane target
`AGENT_WATCH_COLS`	Capture width
`AGENT_WATCH_ROWS`	Capture height
`AGENT_WATCH_FORMAT`	Output format (json/text/png)
`AGENT_WATCH_SESSION_SECRET`	Session signing key

SSL Configuration¶

For HTTPS, generate a self-signed certificate:

mkdir -p ~/.config/agentwatch/certs
openssl req -x509 -newkey rsa:4096 -keyout ~/.config/agentwatch/certs/key.pem \
  -out ~/.config/agentwatch/certs/cert.pem -days 365 -nodes \
  -subj "/CN=localhost"

Then configure in config.yaml:

web_viewer:
  ssl_cert: ~/.config/agentwatch/certs/cert.pem
  ssl_key: ~/.config/agentwatch/certs/key.pem

Cloudflare Tunnel Setup¶

For secure remote access without port forwarding:

# Install cloudflared
brew install cloudflared  # macOS

# Create tunnel
cloudflared tunnel login
cloudflared tunnel create agentwatch

# Create config file
cat > ~/.cloudflared/config-agentwatch.yml << EOF
tunnel: <tunnel-id>
credentials-file: ~/.cloudflared/<tunnel-id>.json
ingress:
  - hostname: agentwatch.yourdomain.com
    service: https://localhost:8081
    originRequest:
      noTLSVerify: true
  - service: http_status:404
EOF

# Add DNS route
cloudflared tunnel route dns <tunnel-id> agentwatch.yourdomain.com

# Enable in config.yaml
cloudflare:
  enabled: true
  config_file: ~/.cloudflared/config-agentwatch.yml