Skip to content

Core Concepts

Understanding how agentwatch works.

What agentwatch Does

agentwatch monitors tmux sessions by:

  1. Capturing terminal content at regular intervals
  2. Detecting which program is running
  3. Determining the program's current state
  4. Firing hooks when state changes
  5. Serving a web interface for viewing and interaction

Programs

agentwatch detects these programs running in tmux:

Program Detection Method
Claude Code Version header (Claude Code vX.Y.Z), UI patterns
Codex Header detection, prompt patterns
bash/zsh Shell prompt patterns ($, %, user@host)

When multiple patterns match, agentwatch uses confidence scores to determine the most likely program.

States

Each detected program has a current state:

Idle

The program is waiting for input at its prompt.

Examples:

  • Claude Code showing ❯ prompt, ready for a task
  • Shell showing $ prompt, waiting for a command

Working

The program is actively processing.

Examples:

  • Claude Code thinking (spinner visible)
  • Claude Code running a command
  • Shell executing a long-running process

Blocked

The program needs user action to continue.

Claude Code examples:

  • Permission dialog ("Allow this action?")
  • Confirmation prompt ("Proceed?")
  • Question requiring input

How agentwatch detects this:

  • UI elements indicating a choice is needed
  • Prompt patterns that aren't the normal input prompt

Error

Something went wrong.

Examples:

  • Claude Code displaying an error message
  • Command failed with non-zero exit
  • Crash or unexpected termination

State Transitions

agentwatch tracks state transitions over time:

Session Start → Idle → Working → Idle → Working → Blocked → Idle → Working → Error
                 ↑                                                              │
                 └──────────────────────────────────────────────────────────────┘
                                    (after recovery)

Each transition includes:

  • Previous state - What state we came from
  • Current state - What state we're in now
  • Detail - Additional context (e.g., "Reading file", "Permission dialog")
  • Duration - How long we were in the previous state
  • Timestamp - When the transition occurred

The Daemon

The agentwatch daemon is a background service that:

Session Discovery

Periodically scans for tmux sessions:

service:
  session_discovery_interval: 5  # Check for new sessions every 5 seconds

New sessions are automatically picked up. Removed sessions are cleaned up.

Capture Loop

For each session, captures terminal state:

service:
  capture_interval: 1  # Capture each session every second

Higher intervals reduce CPU usage but delay state detection.

State Store

Maintains current state for each session in memory:

  • Current program and version
  • Current state and detail
  • State history for transitions
  • Cached parsed output (for session CLI clients)

Hooks Engine

Fires configured hooks on state changes. See Hooks Guide.

Web Server

Serves:

  • Web viewer - Live terminal streaming UI
  • REST API - Programmatic access (browser cookie auth)
  • WebSocket - Real-time terminal updates
  • Session-control API - Dual-auth /api endpoints driven by the agentwatch session CLI

Detection Details

How Detection Works

Each capture goes through detection:

  1. Raw capture - tmux's terminal content with ANSI codes
  2. Program detection - Pattern matching on terminal content
  3. State detection - Program-specific state inference
  4. Confidence scoring - Each detection has a confidence (0-1)

Claude Code Detection

Claude Code is detected by:

  • Version header: Claude Code v1.0.30 (or similar)
  • UI elements: Box borders, prompts
  • State indicators: Spinners, permission dialogs, error messages

State detection looks for:

Pattern State Detail
Spinner characters (✽✳✢✶✻⠋⠙...) Working Processing
❯ prompt alone Idle Ready
Permission dialog keywords Blocked Permission dialog
Error keywords Error Error message

Shell Detection

Shell sessions are detected by prompt patterns:

  • user@host:path$
  • $ at end of line
  • % (zsh default)

Shells are always considered Idle (command execution isn't tracked).

Session Naming

Sessions are identified by the name assigned when agentwatch creates them:

# Create an agentwatch-owned session
agentwatch session new --name coding --dir "$PWD" --agent claude_code

# This session appears as "coding" in agentwatch

The web viewer and API use these names to reference sessions. Hand-started tmux sessions are not monitored or exposed.

Viewer Tags

When a browser connects to view a session, it gets a viewer tag (a random word like "pig" or "match"). This appears in logs as [session/viewer]:

[coding/pig] Connected
[coding/pig] State: Working -> Idle

This helps track which viewer caused which actions.

Parse Cache

agentwatch maintains a parse cache of Claude Code conversations. This is populated by agentwatch session parse and used to return structured output without re-parsing.

The cache is invalidated on:

  • State changes
  • An explicit refresh request

Configuration

All behavior is controlled by ~/.config/agentwatch/config.yaml. See Configuration Reference.

Key sections:

  • logging - Log levels and rotation
  • service - Capture intervals, tmux settings
  • web_viewer - Web server settings
  • tunnel - Remote access
  • sessions - Coding session settings
  • hooks - Hook definitions