agentwatch¶

agentwatch is a terminal snapshot and state detection tool for tmux panes. It captures terminal state and detects which program is running (Claude Code, Codex, bash/zsh) along with its operational state (Idle, Working, Blocked, Error).

Features¶

Program Detection - Automatically identifies Claude Code, Codex, or shell sessions
State Detection - Tracks Idle, Working, Blocked, and Error states with detailed context
Multiple Interfaces - HTTP REST, WebSocket streaming, and MCP server
Web Viewer - Live terminal streaming with keyboard input support
Hooks System - Configurable webhooks and shell commands on state changes
Cloudflare Tunnel - Secure remote access without port forwarding

Quick Start¶

Installation¶

# Clone and install
git clone https://github.com/yourusername/agentwatch.git
cd agentwatch
./install.sh

One-Shot Capture¶

# Basic status (one line)
agentwatch

# Full terminal text
agentwatch --text

# JSON output
agentwatch --json

# PNG screenshot
agentwatch --png

Daemon Mode¶

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

# Start daemon
agentwatch start

# Query status
agentwatch status

API Overview¶

agentwatch exposes multiple APIs for integration:

API	Purpose	Documentation
HTTP REST	Web viewer and programmatic access	HTTP API
WebSocket	Live terminal streaming	WebSocket API
MCP Server	Claude Desktop / MCP client integration	MCP Server API

Architecture¶

┌─────────────────────────────────────────────────────────────┐
│                      agentwatch daemon                       │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   tmux      │  │  Detectors  │  │    State Store      │  │
│  │  Monitor    │──│  (Claude,   │──│  (Session State,    │  │
│  │             │  │   Shell)    │  │   Parse Cache)      │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
│         │                                     │              │
│         ▼                                     ▼              │
│  ┌───────────────────────┐  ┌───────────────────────────┐  │
│  │        Hooks          │  │       Web Server          │  │
│  │  (webhook, shell)     │  │    (HTTP, WebSocket)      │  │
│  └───────────────────────┘  └───────────────────────────┘  │
│                                          │                  │
└──────────────────────────────────────────┼──────────────────┘
                                           │
                          ┌────────────────┴────────────────┐
                          │  Browser / curl / MCP clients   │
                          └─────────────────────────────────┘

Configuration¶

See the Configuration page for full YAML configuration reference.

Requirements¶

Python 3.9+
tmux
uv (for running as script)

Optional: - cloudflared (for Cloudflare Tunnel)