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:

https://localhost:8081/

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:

https://your-subdomain.agentwatch.sh/

See Remote Access Guide for setup instructions.

Authentication¶

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 or Codex 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
New	Agent is Idle	Start a new conversation (`/clear` in Claude Code, `/new` in Codex)
F2	Codex footer shows `⚠ N warnings · f2 to view` for 30s	Open Codex's warnings

Quick keys are context-aware based on detected UI elements. A key the screen itself advertises (like Codex's F2) appears first, highlighted, once the screen has shown it for 30 seconds, so a passing message never makes it blink in and out.

On a phone the quick keys page two rows at a time. Each device counts which keys you press in each program and state, and puts the most-used keys on the first page. The order changes only when the panel is rebuilt (a state change or a reload), so a key never moves while you reach for it.

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. After agentwatch restart or an update, the browser that was driving gets the driver role back when it reconnects. Other viewers wait as passengers for up to 30 seconds.

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

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
Inbox - The clipboard icon in the title bar opens the session's inbox history. Its badge counts the unread items.
Landscape is the file viewer - Turn the phone to see the file tree and a file side by side. Turn it back to return to the terminal. The tab on the divider hides or shows the file tree.
File links - Tap a file path in the terminal to open it in the file viewer, on its line. In portrait, a "Rotate to view" cue appears; turn the phone to see the file.

For best experience, use a tablet or desktop browser.