Common Issues¶

Solutions for frequently encountered problems.

Installation Issues¶

Command not found after install¶

If agentwatch isn't recognized:

# Check if ~/.local/bin is in PATH
echo $PATH | grep -q "$HOME/.local/bin" && echo "OK" || echo "Missing"

# Add to shell config
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Permission denied during install¶

# Create directory with correct permissions
mkdir -p ~/.local/bin
chmod 755 ~/.local/bin

# Retry install
curl https://agentwatch.sh | bash

Python version too old¶

agentwatch requires Python 3.10+:

python3 --version

# If < 3.10, install newer Python
# macOS:
brew install python@3.11

# Linux:
sudo apt install python3.11

Daemon Issues¶

Daemon won't start¶

Check for existing processes:

# Check if already running
pgrep -f agentwatch

# Check logs
tail -50 ~/.cache/agentwatch/daemon.log

# Try foreground mode for debugging
agentwatch start -f

Port 8081 already in use¶

# Find what's using the port
lsof -i :8081

# Kill if needed
kill $(lsof -ti :8081)

# Or change port in config
web_viewer:
  port: 8082

Service file issues¶

Linux (systemd)macOS (launchd)

# Check service status
systemctl --user status agentwatch

# View service logs
journalctl --user -u agentwatch -f

# Reload after config changes
systemctl --user daemon-reload
systemctl --user restart agentwatch

# Check if loaded
launchctl list | grep agentwatch

# View logs
tail -f ~/Library/Logs/com.agentwatch.log

# Reload
launchctl unload ~/Library/LaunchAgents/com.agentwatch.plist
launchctl load ~/Library/LaunchAgents/com.agentwatch.plist

Service-manager restarts are cold

systemctl --user restart agentwatch and launchctl unload/load bypass the CLI, so they drop the tunnel and log you out. Use agentwatch restart when you want to stay logged in (see Logged out after every restart).

Authentication Issues¶

Verify credentials work locally:
```
# Test your password
su - $(whoami)
```

Check you're the daemon user:

# The daemon runs as:
ps aux | grep agentwatch | grep -v grep

Check PAM configuration (Linux):
```
# Test PAM auth
agentwatch auth-test
```

Session expired too quickly¶

Sessions last 24 hours. If expiring sooner:

# Check system clock
date

# Check session secret exists
ls -la ~/.cache/agentwatch/session-secret

Logged out after every restart¶

Use agentwatch restart to restart the daemon. It preserves your web-viewer login (and hands off the Cloudflare tunnel) across the restart. A stop + start, a crash, a reboot, or a service-manager restart (systemctl --user restart agentwatch, launchctl unload/load) is a cold restart and intentionally logs you out — reserve those for when you want a clean slate / forced re-auth.

# Continuity-preserving (stay logged in):
agentwatch restart

# Cold restart (forces fresh login):
agentwatch stop && agentwatch start

Notes:

Continuity is bounded by the normal 24h session expiry; a restart never extends it. A session already past 24h is dropped regardless.
The first restart after upgrading to a build that added login preservation logs you out once (the old daemon writes the pre-upgrade snapshot format, which the new daemon discards). Subsequent restarts preserve login normally.

Remote login uses the same credentials as local:

Ensure tunnel is connected
Try local login first to verify credentials
Check for special characters in password

Detection Issues¶

Wrong state detected¶

If Claude Code shows as Idle when Working (or vice versa):

Enable debug mode:

service:
  debug:
    enabled: true
    capture_dir: ~/.cache/agentwatch/captures
    log_state_changes: true

Restart daemon:
```
agentwatch restart
```

Reproduce the issue and check captures:

grep "STATE CHANGE" ~/.cache/agentwatch/daemon.log | tail -5
# Find the capture file mentioned
cat ~/.cache/agentwatch/captures/session/capture_*.txt

Report the issue with the capture file

Program not detected¶

If showing "Unknown" or wrong program:

Check tmux session has content:
```
tmux capture-pane -p -t session_name
```

Ensure program is running (not just a shell):

tmux list-panes -t session_name -F "#{pane_current_command}"

Spinner characters not recognized¶

New spinner characters may need adding. Check if your Claude Code version uses new spinners:

# Look for spinner-like characters in capture
cat ~/.cache/agentwatch/captures/*/capture_*.txt | grep -o '[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏✽✳✢✶✻·]'

Report any unrecognized spinner characters.

Hook Issues¶

Hooks not firing¶

Check hook configuration:

agentwatch config show | grep -A 20 hooks

Enable hook logging:
```
service:
  debug:
    log_hooks: true
```

Check logs for hook activity:

grep "hook" ~/.cache/agentwatch/daemon.log

Webhook errors¶

Test endpoint manually:

curl -X POST https://your-server.com/webhook \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Check timeout:

hooks:
  - name: my-hook
    timeout_seconds: 30  # Increase if needed

Check for SSL issues (if HTTPS):

curl -v https://your-server.com/webhook 2>&1 | grep -i ssl

Shell hooks fail silently¶

Test command directly:

SESSION_NAME=test STATE=Idle DETAIL="Ready" bash -c 'your_command_here'

Check command permissions:
```
which notify-send  # or your command
```

Enable dry run to see what would execute:

service:
  debug:
    dry_run_hooks: true

Tunnel Issues¶

Tunnel not connecting¶

Check daemon status:
```
agentwatch status
```
Verify device token:
```
cat ~/.config/agentwatch/tokens/device
```
Check tunnel process:
```
ps aux | grep cloudflared
```

View tunnel logs:

grep -i tunnel ~/.cache/agentwatch/daemon.log

Can't reach remote URL¶

Test local first:
```
curl -sk https://localhost:8081/health
```
Check DNS resolution:
```
dig your-subdomain.agentwatch.sh
```
Verify tunnel is running:
```
agentwatch status
```

Web Viewer Issues¶

Black screen / no terminal¶

Check session exists:
```
tmux list-sessions
```
Check capture works:
```
agentwatch capture SESSION --text
```
Check browser console for JavaScript errors

Keys not sending¶

Ensure you're the driver (check header badge)
Click in terminal area to focus
Check connection (status indicator should be green)

Slow/laggy¶

Reduce quality in viewer settings
Check network:
```
ping your-subdomain.agentwatch.sh
```
Reduce FPS in config:
```
web_viewer:
  fps: 1.0
```

Coding Session Issues¶

`agentwatch session` commands fail¶

The agentwatch session ... CLI talks to the running daemon's /api endpoints. If commands fail:

Verify the daemon is running:
```
agentwatch status
```
Check the API token exists:
```
cat ~/.config/agentwatch/tokens/api
```
Try a simple read against the daemon:
```
agentwatch session list --json
```

Session limit reached¶

Default limit is 3 sessions. Increase in config:

sessions:
  max_sessions: 10

Permission errors on `session new`¶

Check allowed_workdirs:

sessions:
  allowed_workdirs:
    - "~"
    - "/your/project/path"

Getting Help¶

If you can't resolve an issue:

Check existing issues: GitHub Issues

Gather diagnostic info:

agentwatch --version-json
agentwatch status
tail -100 ~/.cache/agentwatch/daemon.log

Open a new issue with:
What you expected
What actually happened
Steps to reproduce
Diagnostic output above