Skip to content

Session Resume

Overview

CAI provides powerful session resume capabilities that allow you to continue where you left off. Whether you were in the middle of a security audit, bug bounty session, or complex analysis, you can seamlessly restore your conversation history and pick up exactly where you stopped.

The session resume system automatically saves all your interactions to JSONL log files and provides multiple ways to restore them:

  • --resume: Resume from specific session or interactive selector
  • --resume --continue: Resume AND continue autonomously
  • Interactive Selector: Visual session browser with pagination

Quick Start

# Resume the last session
cai --resume

# Resume the last session and continue autonomously
cai --resume --continue

# Interactive session selector
cai --resume list

# Resume a specific session by ID
cai --resume abc12345

# Resume from a specific log file
cai --resume /path/to/session.jsonl

Session Resume Options

Resume Last Session

cai --resume
# or
cai --resume last

This automatically finds and loads the most recent session that contains messages. Empty sessions are skipped.

Interactive Session Selector

cai --resume list

Opens an interactive menu with:

  • Arrow key navigation (↑/↓ or j/k)
  • Page navigation (←/→ or h/l)
  • Session preview showing last assistant response
  • Cost and token tracking per session
  • Model information for each session
╭──────────────────────────────────────────────────────────────────────────────╮
│  ↻ Select a session to resume                                                │
│  ↑/↓/j/k navigate  │  ←/→/h/l pages  │  Enter select  │  q/Esc cancel       │
╰──────────────────────────────────────────────────────────────────────────────╯

   Page 1+ │ 10 sessions │ → next

   ID       │ Date       │ Model        │ Msgs    │ Cost
   ─────────┼────────────┼──────────────┼─────────┼────────
 ❯ abc12345 │ 01-12 15:30 │ claude-sonnet │  42 msgs │   $2.35 ★ LATEST
   def67890 │ 01-12 14:15 │ gpt-4         │  28 msgs │   $1.80
   ghi11223 │ 01-11 20:00 │ claude-opus   │ 156 msgs │  $12.50

   ──────────────────────────────────────────────────────────────────
   Preview:
   The vulnerability analysis is complete. I found 3 critical issues:
   1. SQL injection in user.py line 45...

Resume with Continue Mode

cai --resume --continue
# or
cai --resume -c

This powerful combination: 1. Restores your previous session with full conversation history 2. Automatically generates a continuation prompt based on context 3. Continues working autonomously without waiting for user input

Perfect for: - Resuming long-running security audits - Continuing interrupted penetration tests - Picking up complex analysis tasks

Resume Specific Session

# By session ID (first 8 characters)
cai --resume abc12345

# By full log file path
cai --resume logs/cai_20240112_153045.jsonl

# From custom logs directory
cai --resume my_session --logpath ~/custom_logs/

What Gets Restored

When you resume a session, CAI restores:

Component Description
Message History All user messages and agent responses
Tool Calls Complete record of tools used and their outputs
Agent Context The agent's understanding of the task
Session Statistics Total cost, tokens used, active time
Parallel Agent Config Multi-agent configurations (if applicable)

Session Statistics Display

↻ Resuming session
claude-sonnet │ Tokens: 45,230in/12,450out │ $3.45 │ 25.3s active

[Session content displayed here...]

Session restored. Continue where you left off.
Restored session stats: $3.4500, 45230in/12450out tokens
Loaded 156 messages into agent history

Custom Logs Directory

Use --logpath to work with sessions stored in custom directories:

# Resume from custom directory
cai --resume list --logpath ~/projects/security_audits/logs/

# Resume last session from custom directory
cai --resume --logpath /shared/team_sessions/

The --logpath option: - Recursively searches all subdirectories for .jsonl files - Works with both --resume list and --resume last - Supports absolute and relative paths

Parallel Agent Sessions

When resuming a session that used multiple parallel agents, CAI automatically detects and offers to restore the parallel configuration:

The session used 3 parallel agents:
  - CTF agent
  - Code Analyzer agent
  - Security Researcher agent

Set up the same parallel agent configuration? (y/n):

If you choose yes, the parallel agent configuration is restored and you can continue working with the same multi-agent setup.

Session Log Format

Sessions are stored as JSONL (JSON Lines) files in the logs/ directory:

logs/
├── last -> cai_20240112_153045.jsonl  # Symlink to most recent
├── cai_20240112_153045.jsonl
├── cai_20240112_140000.jsonl
└── cai_20240111_200000.jsonl

Each log file contains: - Session metadata (ID, timestamps, model info) - Complete message history - Tool calls and responses - Token usage and cost tracking - Timing metrics (active/idle time)

Environment Variables

# Custom default logs directory
export CAI_LOGS_DIR=~/my_logs

# Enable debug output for resume operations
export CAI_DEBUG=2

Programmatic Usage

Python API

from cai.repl.session_resume import (
    resume_session,
    find_last_session_log,
    interactive_session_selector,
    load_session_into_agent
)

# Find and display session
log_path = find_last_session_log()
messages, used_path, parallel_agents = resume_session(log_path)

# Load into agent
from cai.agents import get_agent_by_name
agent = get_agent_by_name("ctf_agent")
load_session_into_agent(agent, messages, log_path=used_path)

List Recent Sessions

from cai.repl.session_resume import list_recent_sessions

sessions = list_recent_sessions(limit=10)
for session in sessions:
    print(f"{session['session_id'][:8]} - {session['model']} - ${session['total_cost']:.2f}")

Best Practices

1. Regular Session Checkpoints

For long-running tasks, the session is automatically saved after each interaction. You can safely interrupt with Ctrl+C and resume later.

2. Descriptive Initial Prompts

When starting a session you plan to resume later, use descriptive prompts that provide context:

# Good - Clear context for resumption
cai --prompt "Security audit of user authentication in project X, focusing on SQL injection and XSS"

# Less helpful for resumption
cai --prompt "check auth"

3. Use Resume + Continue for Autonomous Work

# Start a long task
cai --continue --prompt "comprehensive security audit of the entire codebase"

# Later, resume and let it continue working
cai --resume --continue

4. Organize Sessions with Custom Paths

# Keep different projects separate
cai --prompt "audit project A" --logpath ~/logs/project_a/
cai --prompt "audit project B" --logpath ~/logs/project_b/

# Resume specific project
cai --resume --logpath ~/logs/project_a/

Troubleshooting

Issue: "No previous session found"

Cause: No valid session logs exist in the logs directory.

Solutions: - Check the logs/ directory exists and contains .jsonl files - Use --logpath to specify a custom directory - Ensure previous sessions completed at least one interaction

Issue: Session loads but context seems lost

Cause: The model's context window may be exceeded.

Solutions: - Resume with a model that has a larger context window - The session will work but older messages may be truncated by the model

Issue: Parallel agents not detected

Cause: The original session may not have used the parallel agent format.

Solutions: - Manually configure parallel agents with /parallel command after resuming - Check that the original session used proper parallel agent configuration

Issue: Cost tracking shows $0.00 after resume

Cause: Session stats couldn't be restored from the log file.

Solutions: - This is cosmetic; the actual costs are still in the log file - Check log file format is valid JSONL

Technical Details

Session Resume Flow

```mermaid graph TD A[cai --resume] --> B{Resume type?} B -->|last| C[Find last session log] B -->|list| D[Interactive selector] B -->|path/id| E[Find specific session]

C --> F[Load messages from JSONL]
D --> F
E --> F

F --> G[Display session content]
G --> H[Restore session stats]
H --> I[Load into agent history]

I --> J{--continue flag?}
J -->|Yes| K[Generate continuation prompt]
J -->|No| L[Wait for user input]

K --> M[Auto-continue working]

```

Core Components

File Purpose
src/cai/repl/session_resume.py Main resume functionality
src/cai/sdk/agents/run_to_jsonl.py JSONL parsing and token stats
src/cai/cli.py CLI integration and --resume handling

Log File Structure

{"event": "session_start", "session_id": "abc12345", "timestamp": "2024-01-12T15:30:45Z"}
{"object": "chat.completion", "model": "claude-sonnet", "messages": [...], "agent_name": "CTF agent"}
{"event": "tool_call", "name": "generic_linux_command", "arguments": {...}}
{"event": "session_end", "cost": {"total_cost": 3.45}, "timing_metrics": {...}}

Summary

Session resume in CAI provides:

  • Seamless continuation of interrupted work
  • Full context restoration including tools and agent state
  • Interactive session browsing with preview and filtering
  • Autonomous resumption with --resume --continue
  • Multi-agent support for parallel session restoration
  • Flexible log management with custom directories

Whether you're conducting security audits, running penetration tests, or performing complex analysis, session resume ensures you never lose your progress.