Session Plugin

Session persistence for conversation history. Save and resume sessions across client restarts with auto-save, checkpointing, and session management.

Name	`session`
Type	Client-configured Plugin
User Commands	`save`, `resume`, `sessions`

Features

Auto-save: Save on exit, interval, or after N turns
Auto-resume: Optionally resume last session on startup
Session descriptions: Model-generated names for easy identification
Session limits: Automatic cleanup of old sessions
Token accounting: Track token usage per session

Basic usage

from shared.plugins.session import FileSessionPlugin
from shared.plugins.session.base import SessionConfig

# Create session plugin with config
session_plugin = FileSessionPlugin()
session_plugin.initialize(SessionConfig(
    storage_path='.jaato/sessions',
    auto_save_on_exit=True,
    checkpoint_after_turns=5,
))

# Configure on client
client.configure_session(session_plugin=session_plugin)

User commands

> save
Session saved: 20240115_143022

> sessions
Available sessions:
  20240115_143022 - "Refactoring auth module"
  20240114_091500 - "Setting up CI/CD"
  20240113_160000 (unnamed)

> resume 20240114_091500
Session resumed: 20240114_091500

SessionConfig

Storage Settings

Parameter	Type	Default
`storage_path`	`str`	`".jaato/sessions"`

Auto-save Settings

Parameter	Type	Default
`auto_save_on_exit`	`bool`	`True`
`auto_save_interval`	`int \| None`	`None`
`checkpoint_after_turns`	`int \| None`	`None`

Resume Settings

Parameter	Type	Default
`auto_resume_last`	`bool`	`False`

Naming Settings

Parameter	Type	Default
`request_description_after_turns`	`int`	`3`

Cleanup Settings

Parameter	Type	Default
`max_sessions`	`int`	`20`

Configuration examples

# Minimal: just save on exit
config = SessionConfig()

# Aggressive checkpointing
config = SessionConfig(
    auto_save_on_exit=True,
    auto_save_interval=60,      # Every minute
    checkpoint_after_turns=3,   # After every 3 turns
)

# Auto-resume workflow
config = SessionConfig(
    auto_resume_last=True,
    auto_save_on_exit=True,
)

# Long-running sessions
config = SessionConfig(
    max_sessions=100,
    request_description_after_turns=5,
)

SessionState

Complete state saved for each session:

Field	Type	Description
`session_id`	`str`	Timestamp-based ID
`history`	`List[Message]`	Conversation history
`created_at`	`datetime`	Session creation time
`updated_at`	`datetime`	Last save time
`description`	`str \| None`	Model-generated name
`turn_count`	`int`	Number of turns
`turn_accounting`	`List[Dict]`	Token usage per turn
`user_inputs`	`List[str]`	Original prompts
`project`	`str \| None`	Cloud project ID (if applicable)
`location`	`str \| None`	Provider region (if applicable)
`model`	`str \| None`	Model name

Session file structure

.jaato/
  sessions/
    20240115_143022.json
    20240114_091500.json
    20240113_160000.json

Session JSON format

{
  "session_id": "20240115_143022",
  "description": "Refactoring auth module",
  "created_at": "2024-01-15T14:30:22",
  "updated_at": "2024-01-15T15:45:00",
  "turn_count": 12,
  "turn_accounting": [
    {"prompt": 150, "output": 200, "total": 350},
    {"prompt": 500, "output": 1200, "total": 1700}
  ],
  "project": "my-project",
  "location": null,
  "model": "claude-sonnet-4-20250514",
  "history": [...]
}

User Commands

save

Save current session with optional description.

save [description]

resume

Resume a previously saved session by ID.

resume <session_id>

sessions

List all saved sessions with metadata.

sessions

User Input Restoration

When resuming a session, the plugin can restore original user inputs to the prompt history for readline/up-arrow navigation.

Command examples

> save "Working on auth refactor"
Session saved: 20240115_143022
Description: "Working on auth refactor"

> sessions
Available sessions:
  1. 20240115_143022 - "Working on auth refactor" (12 turns)
  2. 20240114_091500 - "Setting up CI/CD" (8 turns)
  3. 20240113_160000 (unnamed, 3 turns)

> resume 20240114_091500
Resuming session: 20240114_091500
Description: "Setting up CI/CD"
Turns: 8
Model: claude-sonnet-4-20250514

Session resumed successfully.