Debugging Guide¶

How to diagnose and debug agentwatch issues.

Debug Mode¶

Enable debug mode for detailed logging and capture files.

Configuration¶

service:
  debug:
    enabled: true
    capture_dir: ~/.cache/agentwatch/captures
    retention_hours: 4.0
    log_captures: false
    log_detections: false
    log_state_changes: true
    log_hooks: true
    dry_run_hooks: false

Option	Default	Description
`enabled`	false	Enable debug mode
`capture_dir`	null	Save captures to this directory
`retention_hours`	4.0	Auto-delete captures older than this
`log_captures`	false	Log every capture (very verbose)
`log_detections`	false	Log detection results
`log_state_changes`	true	Log state transitions
`log_hooks`	true	Log hook execution
`dry_run_hooks`	false	Log hooks without executing

Enabling¶

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

# Restart daemon
agentwatch restart

Log Files¶

Daemon Log¶

Main log file: ~/.cache/agentwatch/daemon.log

# View recent logs
tail -100 ~/.cache/agentwatch/daemon.log

# Follow logs
tail -f ~/.cache/agentwatch/daemon.log

# Search for errors
grep -i error ~/.cache/agentwatch/daemon.log

Log Levels¶

Set in config:

logging:
  log_level: DEBUG  # DEBUG, INFO, WARNING, ERROR

Log Rotation¶

Logs rotate automatically:

logging:
  log_rotate_max_mb: 10        # Max size per file
  log_rotate_backup_count: 9   # Keep 9 rotated files

State Change Markers¶

When log_state_changes: true, state changes are logged with markers:

*** STATE CHANGE #123 *** None/Working -> Claude Code/Idle (detail: Ready)

Format: *** STATE CHANGE #N *** prev_program/prev_state -> program/state (detail: detail)

Finding State Changes¶

grep "STATE CHANGE" ~/.cache/agentwatch/daemon.log

Output includes the capture file that triggered the change:

*** STATE CHANGE #123 *** ... -> capture_20260204_135703_000123.txt

Capture Files¶

When capture_dir is set, terminal content is saved on state changes.

Structure¶

~/.cache/agentwatch/captures/
└── session-name/
    ├── capture_20260204_135703_000001.txt
    ├── capture_20260204_135704_000002.txt
    └── ...

Filename Format¶

capture_YYYYMMDD_HHMMSS_NNNNNN.txt

Date and time of capture
6-digit sequence number

Viewing Captures¶

# List captures for a session
ls -la ~/.cache/agentwatch/captures/my-session/

# View a specific capture
cat ~/.cache/agentwatch/captures/my-session/capture_*.txt | head -50

# Find capture mentioned in log
grep "capture_20260204" ~/.cache/agentwatch/daemon.log

Auto-Cleanup¶

Captures older than retention_hours are automatically deleted.

Using the logs Command¶

The agentwatch logs command extracts and displays logs.

# List all sessions and viewers
agentwatch logs --list

# Logs for a session
agentwatch logs my-session

# Logs for a session/viewer pair
agentwatch logs my-session/pig

# Follow logs
agentwatch logs my-session --tail

# Last N entries
agentwatch logs my-session -n 50

# Include capture contents
agentwatch logs my-session --captures

# Only captures (no log entries)
agentwatch logs my-session --captures-only

Log Session Format¶

Logs use [session/viewer] tags:

[coding/pig] Connected from 192.168.1.100
[coding/pig] State: Working -> Idle
[coding] Session discovery: found 3 sessions

[session/viewer] - Browser viewer connected
[session] - Daemon activity for session

Debugging Detection¶

False Idle Detection¶

If Claude shows as Idle when actually Working:

Enable capture files:

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

Reproduce the issue

Find the state change:

grep "STATE CHANGE.*Working.*Idle" ~/.cache/agentwatch/daemon.log

View the capture file mentioned
Look for:
Missing spinner characters
New status line format
Unexpected UI changes

False Working Detection¶

If Claude shows as Working when actually Idle:

Same steps as above
Look for:
Stale status lines
Status duration > 5 minutes with prompt visible
New completion message format

Reporting Detection Issues¶

When reporting, include:

The capture file content
Expected vs actual state
Claude Code version
agentwatch version

Debugging Hooks¶

Dry Run Mode¶

Test hooks without executing:

service:
  debug:
    dry_run_hooks: true
    log_hooks: true

Logs show what would execute:

[DRY RUN] Would execute hook 'my-webhook': POST https://example.com
[DRY RUN] Would execute hook 'my-shell': echo "$SESSION_NAME"

Hook Environment¶

Test shell hook environment:

# Simulate hook environment
SESSION_NAME="test" \
STATE="Idle" \
DETAIL="Ready" \
PREVIOUS_STATE="Working" \
TIMESTAMP="2026-02-19T10:00:00Z" \
bash -c 'echo "Session: $SESSION_NAME, State: $STATE"'

Webhook Testing¶

Test webhook endpoint:

curl -X POST https://your-server.com/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "session_name": "test",
    "program": "Claude Code",
    "state": "Idle",
    "detail": "Ready"
  }'

Debugging Web Viewer¶

Browser Console¶

Check browser developer console for errors:

Open DevTools (F12)
Check Console tab for errors
Check Network tab for failed requests

Remote Logging¶

The web viewer sends logs to the daemon. View them:

grep "REMOTE LOG" ~/.cache/agentwatch/daemon.log

WebSocket Connection¶

Check WebSocket status in browser:

DevTools → Network tab
Filter by "WS"
Check connection status and messages

Debugging Coding Sessions¶

Coding sessions are managed via the agentwatch session ... CLI, which calls the daemon's /api endpoints (dual-auth: session cookie or Bearer token from ~/.config/agentwatch/tokens/api).

Test the API Endpoints¶

TOKEN=$(cat ~/.config/agentwatch/tokens/api)

# List sessions
curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8081/api/state/sessions

# Health check
curl -sk https://localhost:8081/api/health

Session Errors¶

Check daemon logs for session-related errors:

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

Session Creation Issues¶

# Check allowed workdirs
agentwatch config show | grep -A 5 allowed_workdirs

# Check max sessions
agentwatch config show | grep max_sessions

# List current sessions
agentwatch session list --json

Performance Debugging¶

High CPU Usage¶

Check capture interval:

service:
  capture_interval: 2  # Increase from 1

Check number of sessions:
```
tmux list-sessions | wc -l
```
Check for runaway processes:
```
ps aux | grep agentwatch
```

High Memory Usage¶

Disable capture files:

service:
  debug:
    capture_dir: null

Reduce log retention:

logging:
  log_rotate_max_mb: 5
  log_rotate_backup_count: 3

Slow State Detection¶

Enable detection logging:

service:
  debug:
    log_detections: true

Check for long detection times in logs

Getting More Help¶

If debugging doesn't resolve the issue:

Collect all relevant info:

agentwatch --version-json > debug-info.txt
agentwatch status >> debug-info.txt
tail -200 ~/.cache/agentwatch/daemon.log >> debug-info.txt

Open a GitHub issue with:
Description of the problem
Steps to reproduce
debug-info.txt contents
Any relevant capture files