Quickstart¶

Get agentwatch running in under 2 minutes.

Prerequisites¶

A Unix-like system (Linux or macOS)
tmux installed

Step 1: Install¶

curl https://agentwatch.sh | bash

Step 2: Run Setup¶

agentwatch setup

The wizard walks you through:

API token - Automatically generated for secure access
Remote access - Option to set up agentwatch.sh tunnel
Start daemon - Launches the monitoring service

Step 3: Open Web Viewer¶

After setup, open the URL shown (or run agentwatch status to see it):

Local: https://localhost:8081/
Remote: https://your-subdomain.agentwatch.sh/ (if tunnel configured)

Self-signed certificate

The local URL uses a self-signed certificate. Accept the browser warning to continue.

Enter your system username and password. This is the same login you use for your computer.

What You'll See¶

The web viewer shows agentwatch-spawned sessions:

Session list - Sessions created from the web viewer or agentwatch session new
Terminal view - Live terminal output
State indicator - Current program and state (Idle, Working, Blocked, Error)
Quick keys - Buttons for common actions

Hand-started tmux sessions are not monitored or exposed.

Try It Out¶

Start Claude Code through agentwatch:

agentwatch session new --dir "$PWD" --agent claude_code

Watch the web viewer - It should show the new session and its state
Give Claude a task - Watch the state change from Idle to Working
See state transitions - When Claude finishes or needs input, the state updates

What's Running¶

After setup, you have:

Component	Description
agentwatch daemon	Background service monitoring agentwatch-spawned tmux sessions
Web server	HTTPS server on port 8081 for the viewer and API
Tunnel (optional)	Cloudflare tunnel for remote access

Check what's running:

agentwatch status

Next Steps¶

Configure Hooks¶

Get notified when sessions change state:

# Edit config
$EDITOR ~/.config/agentwatch/config.yaml

Add a hook:

hooks:
  - name: notify-idle
    type: shell
    trigger: state_change
    to_states: [Idle]
    command: 'echo "$SESSION_NAME finished" >> ~/agentwatch.log'

Then restart:

agentwatch restart

Full hooks guide

Orchestrate Coding Sessions¶

Create and manage coding sessions from the command line:

# Spawn a Claude Code session on a task
agentwatch session new --dir ~/myproject --task "Add a healthcheck endpoint"

# Check on it, then wait for it to need attention
agentwatch session list
agentwatch session wait myproject

Agents can drive sessions on a remote machine over SSH with no extra config:

ssh HOST agentwatch session new --dir ~/myproject --task "..."

Multi-agent guide

Set Up Remote Access¶

If you didn't configure a tunnel during setup:

agentwatch setup --token <YOUR_DEVICE_TOKEN>
agentwatch restart

Get a device token from the agentwatch dashboard.

Remote access guide

Common Commands¶

# Service
agentwatch start              # Start daemon
agentwatch stop               # Stop daemon
agentwatch restart            # Restart daemon
agentwatch status             # Show status

# Debugging
agentwatch logs SESSION       # View logs for a session
agentwatch --text             # One-shot terminal capture

# Configuration
agentwatch config show        # Show current config
agentwatch setup              # Re-run setup wizard

Stopping agentwatch¶

# Stop the daemon
agentwatch stop

# Or uninstall completely
agentwatch uninstall