Skip to content

agentwatch

Monitor AI coding assistants. Get notified. Stay in control.

agentwatch watches your tmux sessions running AI coding assistants like Claude Code or Codex. It detects their current state, fires hooks when things change, and provides a web interface for remote terminal viewing.

Why agentwatch?

Running AI coding assistants in terminal sessions creates a supervision challenge:

  • They work autonomously - You don't know when they need input
  • They hit errors - Silent failures waste your time
  • They finish tasks - But you're working on something else
  • They're in tmux - Checking them means context switching

agentwatch solves this by continuously monitoring your sessions and notifying you when something needs attention.

Key Features

  • State Detection

    Automatically detects Idle, Working, Blocked, and Error states for Claude Code, Codex, and shell sessions.

    Learn about states

  • Web Viewer

    Live terminal streaming with keyboard input. Access from anywhere with OS authentication and optional remote tunneling.

    Web viewer guide

  • Hooks System

    Configure webhooks and shell commands to fire on state changes. Get notified when sessions need attention.

    Hooks guide

  • Multi-Agent Orchestration

    Drive coding sessions from the agentwatch session CLI. Create sessions, send input, and check status programmatically over SSH or locally.

    Multi-agent guide

How It Works

┌─────────────────────────────────────────────────────────────────────┐
│                          agentwatch daemon                          │
│                                                                     │
│  ┌─────────────────┐    ┌─────────────────┐    ┌────────────────┐  │
│  │  Session        │    │   Detection     │    │   State        │  │
│  │  Discovery      │───▶│   Engine        │───▶│   Store        │  │
│  │  (tmux)         │    │   (patterns)    │    │   (per-session)│  │
│  └─────────────────┘    └─────────────────┘    └────────────────┘  │
│                                                        │            │
│                         ┌──────────────────────────────┤            │
│                         ▼                              ▼            │
│  ┌─────────────────────────────────┐    ┌─────────────────────────┐│
│  │         Hooks Engine            │    │      Web Server         ││
│  │  • Webhooks (HTTP POST)         │    │  • Live terminal view   ││
│  │  • Shell commands               │    │  • Keyboard input       ││
│  │  • State change triggers        │    │  • REST API             ││
│  └─────────────────────────────────┘    │  • /api session control ││
│                                         └─────────────────────────┘│
└─────────────────────────────────────────────────────────────────────┘
                                                   │
                        ┌──────────────────────────┴───────────────────┐
                        │                                              │
              ┌─────────▼─────────┐                    ┌───────────────▼───────┐
              │   Web Browser     │                    │  session CLI clients  │
              │   • View sessions │                    │   • Orchestrators     │
              │   • Send input    │                    │   • CI / automation   │
              │   • Quick keys    │                    │   • SSH agents        │
              └───────────────────┘                    └───────────────────────┘

Quick Start

Get started in under a minute:

# Install
curl https://agentwatch.sh | bash

# Run setup wizard
agentwatch setup

# Start the daemon
agentwatch start

The setup wizard configures authentication and opens the web viewer in your browser.

Full quickstart guide

Supported Programs

Program Detection Method States
Claude Code Version header, spinner patterns, prompt detection Idle, Working, Blocked, Error
Codex Header detection, UI patterns Idle, Working, Blocked, Error
bash/zsh Prompt patterns ($, %, user@host) Idle

Use Cases

Personal Monitoring

Run Claude Code on complex tasks and get notified:

hooks:
  - name: desktop-notify
    type: shell
    trigger: state_change
    to_states: [Blocked, Error, Idle]
    command: 'notify-send "agentwatch" "$SESSION_NAME: $STATE"'

CI/CD Integration

Fire webhooks to trigger downstream jobs:

hooks:
  - name: ci-trigger
    type: webhook
    trigger: state_change
    programs: ["Claude Code"]
    to_states: [Idle]
    url: "https://ci.example.com/trigger"
    include: json

Multi-Agent Orchestration

Use the agentwatch session CLI to coordinate multiple coding sessions:

# Create sessions
agentwatch session new --dir ~/projectA --task "Implement feature A"
agentwatch session new --dir ~/projectB --task "Write tests for feature B"

# Wait for any to need attention
agentwatch session wait-any featA featB

Next Steps