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 - Unix socket, 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
./start.sh

# Query status
echo "status" | nc -U /tmp/agentwatch.sock

API Overview¶

agentwatch exposes multiple APIs for integration:

API	Purpose	Documentation
Unix Socket	Local daemon queries	Unix Socket API
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     │  │ Unix Socket │  │    Web Server       │  │
│  │  (webhook,  │  │    API      │  │  (HTTP, WebSocket)  │  │
│  │   shell)    │  │             │  │                     │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
│                          │                    │              │
└──────────────────────────┼────────────────────┼──────────────┘
                           │                    │
                    ┌──────┴──────┐      ┌──────┴──────┐
                    │  CLI Tools  │      │  Browser    │
                    │  (nc, curl) │      │  (viewer)   │
                    └─────────────┘      └─────────────┘

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)