Time Travel & Forking

Agent Harbor enables time-travel debugging through filesystem snapshots and session recording. Rewind to any point in an agent’s session, inspect the exact state, and branch off with new instructions.

How It Works

During agent execution, Agent Harbor captures:

1. Terminal I/O — Exact visual terminal state at every moment
2. Filesystem snapshots — Copy-on-write snapshots at logical boundaries
3. Session moments — Labeled points for navigation (auto and manual)

This enables you to scrub through an agent’s session, see exactly what it saw, inspect the filesystem at that point, and create new branches with modified instructions.

Core Concepts

SessionRecording

A terminal I/O timeline capturing exactly what appeared in the terminal. Stored in .ahr format with:

• Timestamped terminal output
• Resize events
• Input capture (optional, with password redaction)

SessionMoment

A labeled point in the recording timeline:

• Auto moments — Created at tool boundaries, command completions
• Manual moments — Created by user interaction

FsSnapshot

A SessionMoment with an associated filesystem snapshot:

• Captures exact workspace state
• Enables seeking to that point
• Allows creating writable branches

SessionBranch

A new session created from a snapshot:

• Writable clone of the filesystem state
• Original session remains immutable
• Can inject a new chat message to redirect the agent

Snapshot Providers

Provider Selection

# Auto-detect best provider
ah agent start --agent claude --fs-snapshots auto --prompt "Task"
 
# Force specific provider
ah agent start --agent claude --fs-snapshots zfs --prompt "Task"
ah agent start --agent claude --fs-snapshots btrfs --prompt "Task"
ah agent start --agent claude --fs-snapshots agentfs --prompt "Task"
ah agent start --agent claude --fs-snapshots git --prompt "Task"

Recording Sessions

Start Recording

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

Headless Recording

ah agent record --headless -o session.ahr -- ah agent start --agent claude --prompt "Fix"

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

The replay viewer shows:

• Exact terminal output with timestamps
• Snapshot indicators in the gutter
• Scrubbing with keyboard navigation

Replay Controls

Creating Branches

From a Snapshot

ah agent start --agent claude --from-snapshot <snapshot-id> --prompt "Try different approach"

Extract Branch Points

ah agent branch-points session.ahr

Output shows all snapshots with their IDs and timestamps.

Intervention Workflow

The complete time-travel workflow:

1. Record the agent session
2. Replay and navigate to the point of interest
3. Pause and inspect the filesystem state
4. Branch with new instructions
5. Compare the original and branched executions

TUI Intervention

In the TUI, press i while paused to:

• Enter a new instruction
• Create a SessionBranch from the current snapshot
• Launch the agent in the branched workspace

REST API

# List timeline with snapshots
GET /api/v1/sessions/{id}/timeline
 
# Create manual snapshot
POST /api/v1/sessions/{id}/fs-snapshots
 
# Seek to a timestamp (returns read-only mount)
POST /api/v1/sessions/{id}/seek
 
# Create a branch
POST /api/v1/sessions/{id}/session-branch

Agent State Restoration

When branching, Agent Harbor restores both filesystem and agent state:

Checkpoint Restore (Best)

For agents that support checkpoints:

• Detects checkpoint near target moment
• Restores from checkpoint ID
• Injects new message after resume

Session Resume with Trim

For agents with conversation logs:

• Copies session files to branch
• Truncates to target timestamp
• Resumes with trimmed history

Prompt Replay (Fallback)

For stateless agents:

• Extracts prompts from recording
• Replays conversation to reconstruct context
• Continues with new instruction

Benefits

Fast Task Startup

Copy-on-write snapshots enable instant workspace creation:

• No file copying
• Minimal memory overhead
• Instant branch creation

Low Disk Usage

Snapshots share unchanged data:

• Only modified blocks stored
• Multiple branches use minimal additional space
• Efficient for parallel agent execution

Path Stability

Unlike git worktrees, AgentFS maintains the same file paths:

• Build caches remain valid
• IDE configurations preserved
• No path rewriting needed

Non-Destructive Experimentation

Create multiple execution paths safely:

• Original session preserved
• Branches are independent
• Compare and cherry-pick results

Limitations

• Full semantic capture of application state (e.g., Vim buffers) is not preserved
• Replay uses fixed terminal grid with recorded resize events
• Agent state restoration fidelity depends on agent support