Web Viewer Guide¶
The agentwatch web viewer provides live terminal streaming with keyboard input support.
Accessing the Viewer¶
Local Access¶
When the daemon is running, access the viewer at:
Self-signed certificate
The local server uses a self-signed certificate. Accept your browser's security warning to continue.
Remote Access¶
If you've configured a tunnel:
See Remote Access Guide for setup instructions.
Authentication¶
OS Login¶
The viewer uses your operating system credentials:
- Username: Your system username
- Password: Your system password
By default, only the user running the daemon can authenticate.
How It Works¶
- macOS: Uses Directory Services (dscl)
- Linux: Uses PAM authentication
Session Duration¶
Login sessions last 24 hours. After that, you'll need to log in again.
Session List¶
After login, you'll see all monitored tmux sessions:
| Column | Description |
|---|---|
| Session | tmux session name |
| Program | Detected program (Claude Code, Codex, bash, etc.) |
| State | Current state (Idle, Working, Blocked, Error) |
| Detail | Additional context |
| Duration | Time in current state |
Click a session to open the terminal view.
Terminal View¶
Live Streaming¶
The terminal view shows live output from the selected session:
- Real-time updates - Content refreshes at ~2 FPS
- ANSI colors - Full color support
- Scrollback - Scroll up to see history
State Badge¶
The header shows:
- Program name and version
- Current state with color coding
- Duration in current state
| Color | State |
|---|---|
| Gray | Idle |
| Blue | Working |
| Yellow | Blocked |
| Red | Error |
Keyboard Input¶
Sending Keys¶
Click in the terminal area and type. Your keystrokes are sent to the tmux session.
Supported keys:
| Key | Action |
|---|---|
| Alphanumeric | Typed directly |
| Enter | Sent as newline |
| Backspace | Delete character |
| Arrow keys | Navigation |
| Ctrl+C | Interrupt |
| Escape | Escape key |
Quick Keys¶
When Claude Code is detected in certain states, quick keys appear:
| Button | When Shown | Action |
|---|---|---|
| y / n | Permission dialog | Approve or deny |
| 1-9 | Multiple choice | Select option |
| Enter | Confirmation prompt | Confirm |
| Esc | Menu/dialog | Cancel |
Quick keys are context-aware based on detected UI elements.
Multi-User Mode¶
Multiple users can view the same session simultaneously.
Roles¶
| Role | Permissions |
|---|---|
| Driver | Can send keyboard input |
| Passenger | View only |
The first user to connect becomes the driver. If the driver disconnects, the next passenger becomes driver.
Driver Indicator¶
The header shows who is currently driving:
[Driver]- You have keyboard control[Viewing]- You're in view-only mode
Taking Control¶
To become driver when you're a passenger:
- Click the "Take Control" button
- The current driver sees a notification
- If they don't respond in 10 seconds, you become driver
Session Selection¶
Switching Sessions¶
Click the session name in the header to return to the session list.
Or use the dropdown to switch directly to another session.
Session Status¶
The session list auto-updates as sessions change state. A badge shows unviewed state changes.
Display Settings¶
Terminal Size¶
The terminal adjusts to fit your browser window. For exact size control:
- Click the gear icon
- Select a preset size or enter custom dimensions
- The view updates immediately
Standard sizes:
- 80x24 (default)
- 120x40 (large)
- Custom
Quality¶
For slow connections, reduce quality:
| Quality | Description |
|---|---|
| High | Full refresh rate (~2 FPS) |
| Medium | Reduced rate (~1 FPS) |
| Low | Minimal updates (~0.5 FPS) |
Troubleshooting¶
Can't Connect¶
- Check the daemon is running:
agentwatch status - Verify the port:
curl -sk https://localhost:8081/health - Check firewall settings
Login Fails¶
- Verify your username/password
- Check you're the user running the daemon
- On Linux, verify PAM is configured
No Sessions Shown¶
- Ensure tmux sessions exist:
tmux list-sessions - Check daemon logs:
agentwatch logs - Verify daemon can access tmux socket
Keys Not Sending¶
- Click in the terminal area first
- Check you're the driver (not passenger)
- Verify the session is still active
Slow/Laggy¶
- Reduce quality in settings
- Check network connection
- Reduce capture interval in config
Keyboard Shortcuts¶
| Shortcut | Action |
|---|---|
Esc |
Return to session list |
Ctrl+. |
Toggle settings |
Ctrl+/ |
Show keyboard shortcuts |
Mobile Usage¶
The viewer works on mobile devices with some limitations:
- Touch input - Tap to focus, use on-screen keyboard
- Quick keys - Larger buttons for touch
- Landscape - Recommended for better terminal visibility
For best experience, use a tablet or desktop browser.