🎬 Session Recording

🔬 Three-Layer Capture Architecture

Session recording captures events at three distinct layers, giving you complete observability into agent behavior.

⚡ Quick Start

Command Line

# Start with recording enabled
devduck --record

# Record a one-shot query
devduck --record "create a web scraper"

# Resume from a recorded session
devduck --resume ~/Desktop/session-20260202-231359.zip

# Resume from specific snapshot
devduck --resume session.zip --snapshot 2

# Resume and continue with new query
devduck --resume session.zip --snapshot 2 "continue from here"

Interactive REPL

# In DevDuck REPL:
record              # Start recording
# ... do your work ...
record              # Stop and export ZIP

Tool API

# Start recording
session_recorder(action="start")

# Create state snapshot with description
session_recorder(action="snapshot", description="after API setup")

# Check recording status
session_recorder(action="status")

# Export without stopping
session_recorder(action="export", output_path="~/Desktop/checkpoint.zip")

# Stop recording and export
session_recorder(action="stop")

💾 Full State Resume

The killer feature: snapshots capture your complete conversation state, allowing you to resume exactly where you left off.

Python Resume API

from devduck import load_session, resume_session, list_sessions

# List all recorded sessions
sessions = list_sessions()
for s in sessions:
    print(f"{s['name']} - {s['size_kb']:.1f}KB - {s['modified']}")

# Quick resume from latest snapshot
result = resume_session("~/Desktop/session.zip")
print(f"Restored {result['messages_restored']} messages")

# Load session for inspection
session = load_session("session.zip")
print(session)  # LoadedSession(id=..., events=14, snapshots=3)

# Explore session data
print(session.metadata)
print(f"Duration: {session.duration}s")
print(f"Resumable: {session.has_pkl}")

# Get events by layer
sys_events = session.get_events_by_layer("sys")
tool_events = session.get_events_by_layer("tool")
agent_events = session.get_events_by_layer("agent")

# Resume from specific snapshot with agent
result = session.resume_from_snapshot(2, agent=devduck.agent)
print(f"Messages restored: {result['messages_restored']}")
print(f"Working directory: {result['cwd']}")

# Resume AND continue with new query
result = session.resume_and_continue(
    snapshot_id=2,
    new_query="continue from where we left off",
    agent=devduck.agent
)
print(result['agent_result'])

📸 What Snapshots Capture

Each snapshot is a complete checkpoint of agent state at that moment in time.

📋 Recording Actions

📦 Export Format

Sessions are exported as ZIP archives containing structured data for analysis, replay, and resume.

Event Structure

{
  "timestamp_ns": 1738539876420000000,
  "layer": "tool",
  "event_type": "tool.call",
  "data": {
    "name": "shell",
    "args": {"command": "ls -la"}
  },
  "trace_id": null
}

Snapshot Structure

{
  "timestamp": 1738539876.42,
  "snapshot_id": 2,
  "agent_messages_count": 12,
  "agent_messages": [
    {"role": "user", "content": "..."},
    {"role": "assistant", "content": "..."}
  ],
  "system_prompt": "🦆 You are DevDuck...",
  "last_query": "read the file and update it",
  "last_result": "Done! I've updated...",
  "model_info": {
    "type": "BedrockModel",
    "model_id": "claude-opus-4-5",
    "provider": "bedrock"
  },
  "tools_loaded": ["shell", "editor", "file_read"],
  "cwd": "/Users/cagatay/project"
}

✨ Features

🔄 Example Workflow

📂 Storage Location

# Default recording directory
/tmp/devduck/recordings/
├── session-20260202-224751.zip
├── session-20260202-231359.zip
└── ...

# List recordings via tool
session_recorder(action="list")

# Export to custom location
session_recorder(action="stop", output_path="~/Desktop/my-session.zip")

# Python API
from devduck import list_sessions
for s in list_sessions():
    print(f"{s['name']} - {s['modified']}")

💡 Use Cases