Session Recording

Agent Harbor records every agent session with full PTY capture. Sessions can be replayed for debugging, analysis, and auditing.

What Gets Recorded

The .ahr (Agent Harbor Recording) format captures:

Content	Description
Terminal output	Full PTY stream with exact timing
Input (optional)	Keystrokes with password redaction
Resize events	Terminal size changes
Session moments	Labeled points (auto and manual)
Filesystem snapshots	References to CoW snapshots
Branch metadata	Parent session, snapshot ID, injected message

Recording Sessions

Basic Recording


ah agent record -o session.ahr -- ah agent start --agent claude --prompt "Add unit tests"

The -- separates recording options from the command being recorded.

Recording Options

Option	Description
`-o, --out-file <PATH>`	Output file (.ahr format)
`--headless`	Disable live viewer
`--cols <N>`	Set terminal columns
`--rows <N>`	Set terminal rows

Headless Recording

For CI/CD or background tasks:


ah agent record --headless -o session.ahr -- ah agent start --agent claude --non-interactive --prompt "Run tests"

Custom Terminal Size


ah agent record --cols 120 --rows 40 -o session.ahr -- ah agent start --agent claude --prompt "Task"

Replaying Sessions

Basic Replay


ah agent replay session.ahr

What Replay Shows

Exact terminal output with original timing
Snapshot indicators in the gutter
Session moments for navigation
Branch points for intervention

Replay Controls

Key	Action
Space	Pause/resume playback
`[` / `]`	Jump to previous/next moment
`{` / `}`	Jump to previous/next snapshot
Arrow keys	Scrub through timeline
`s`	Seek and inspect snapshot
`i`	Intervene (create branch)
`q`	Quit

Session Moments

Moments are labeled points in the timeline for navigation:

Auto Moments

Created automatically at:

Tool invocations (agent tool use)
Shell command completions
Runtime milestones (provisioned, tests passed)

Manual Moments

Created via:

TUI keyboard shortcut
REST API call
CLI command

Extracting Information

List Branch Points


ah agent branch-points session.ahr

Shows all snapshots with IDs and timestamps.

Session Timeline

Via REST API:


GET /api/v1/sessions/{id}/timeline

Returns moments, snapshots, and recording metadata.

Storage and Compression

Brotli compression for efficient storage
Streaming format allows incremental writing
Typical sessions compress to 10-50% of raw size

Performance

Recording adds minimal overhead:

PTY passthrough latency target: under 200ms
Throughput target: 90%+ of native terminal
Adaptive buffering for interactive vs bulk output

Use Cases

Debugging

Replay a failed session to understand what went wrong:


ah agent replay failed-session.ahr

Navigate to the failure point, inspect filesystem state, and understand the sequence of events.

Documentation

Record sessions to document processes:


ah agent record -o tutorial.ahr -- ah agent start --agent claude --prompt "Set up dev environment"

Auditing

Keep records of agent activity for compliance:


ah agent record -o audit-$(date +%Y%m%d).ahr -- ah agent start ...

Intervention

Branch from a recorded session to try a different approach:


# Find branch points
ah agent branch-points session.ahr
 
# Start from a specific snapshot
ah agent start --agent claude --from-snapshot <snapshot-id> --prompt "Try alternative"

Data Retention

Configure retention policies for recordings:

By count (keep last N recordings)
By age (keep for N days)
By size (limit total storage)

Policies apply to both recording files and associated snapshots.

Security Considerations

Keystrokes: When input capture is enabled, password prompts are redacted (based on ECHO off and common prompt patterns)
Access control: Recordings require same permissions as session access
Encryption: Encrypt at rest when stored remotely