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¶

# Logging
logging:
  log_level: INFO                # DEBUG, INFO, WARNING, ERROR
  log_file: ~/.cache/agentwatch/daemon.log  # null = stderr only
  log_rotate_max_mb: 10          # Max size per file (MB)
  log_rotate_backup_count: 9     # Number of rotated files to keep (~100MB total)

# Service settings
service:
  session_discovery_interval: 5  # seconds
  capture_interval: 1            # seconds
  tmux_socket: null              # null = default socket
  capture_cols: 80               # default capture dimensions
  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

# Web viewer settings (HTTPS API server)
web_viewer:
  enabled: true
  # Host to bind
  host: 127.0.0.1
  port: 8081
  # Session secret auto-generated at ~/.cache/agentwatch/session-secret

  # 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: true
  session_prefix: coding-
  max_sessions: 3
  capture_lines: 50

  # Security: Allowed working directories
  # MCP clients can only create sessions under these paths
  # Children of allowed directories are automatically allowed
  allowed_workdirs:
    - "~"         # Home directory and subdirectories
    - "/tmp"      # Temporary files
    - "/var/tmp"  # Persistent temporary files
    # - "/data/projects"  # Add custom paths as needed

# 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¶

AGENTWATCH_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¶

The web viewer requires HTTPS for all connections. Certificates are handled automatically:

Auto-generated localhost certificate: On first start, if no certificates are available, a self-signed localhost certificate is automatically generated at runtime.
Tunnel certificates: When using the auto-provisioned tunnel (tunnel.enabled: true), Cloudflare origin certificates are automatically fetched and used.
Custom certificates: You can provide your own certificates in the config:

web_viewer:
  ssl_cert: /path/to/custom.pem
  ssl_key: /path/to/custom.key

MCP Clients and SSL¶

For MCP clients (Claude Code, Codex), use the stdio transport which handles SSL automatically:

claude mcp add --transport command agentwatch -- agentwatch mcp

The agentwatch mcp command bypasses SSL verification for localhost connections and reads the auth token automatically from ~/.config/agentwatch/tokens/api.

Certificate Priority¶

When multiple certificates are available, they're used in this order: 1. Tunnel certificate (for *.agentwatch.sh domains) 2. User-provided certificate (ssl_cert/ssl_key in config) 3. Auto-generated localhost certificate (for local connections)

SNI (Server Name Indication) is used to serve the correct certificate based on the hostname the client connects to.

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