Sessions List

Overview

When you launch sx, a new session directory is created under .scorpiox/sessions/ with a unique ID derived from the Unix timestamp. Every API request, tool invocation, assistant response, and config state is recorded into structured files inside that directory.

Sessions are the fundamental unit of work in ScorpioX Code. Each session captures the full context: which model was used, what provider handled the requests, every conversation turn, and all tool execution results. This makes sessions fully reproducible and debuggable.

.scorpiox/sessions/session_1716940000/
├── meta.json                 # Session metadata
├── conversation.json         # Full conversation history
├── config-snapshot.txt       # Resolved config at start
├── session.log               # Human-readable log
├── agent.log                 # Agent-level operations
├── events.jsonl              # Structured event stream
├── trace.jsonl               # Data flow trace
└── traffic/
    └── raw/                  # Raw API request/response bodies
        ├── 001-req-body.json
        ├── 001-resp-body.json
        └── ...

Session Directory Structure

The session directory tree is created by sx_session_create() in libsxutil/sx_session.c. The directory layout is fixed — every session has the same structure regardless of model or provider.

~/.scorpiox/                      # Global config directory
├── scorpiox-env.txt              # Configuration file
├── sessions/                     # All sessions
│   ├── session_1716940000/       # Individual session
│   │   ├── meta.json
│   │   ├── conversation.json
│   │   ├── config-snapshot.txt
│   │   ├── session.log
│   │   ├── agent.log
│   │   ├── events.jsonl
│   │   ├── trace.jsonl
│   │   └── traffic/raw/
│   ├── session_1716940500/
│   └── ...
├── conversations/                # Legacy conversation storage
│   └── <id>.json
└── logs/
    └── sx-session.log            # Fallback log location

Project-local sessions are also supported. If PROJECT_DIR is set or a .scorpiox/ directory exists in the working directory, sessions are stored there instead of the global location.

Session Files

Each file in the session directory serves a specific purpose. All are plain text or JSON — no binary formats.

meta.json Schema

{
  "id": "session_1716940000",
  "start_time": "2026-05-29T09:34:18Z",
  "start_epoch": 1716940000,
  "cwd": "/home/user/project",
  "model": "opus",
  "provider": "claude_code",
  "log_level": "INFO",
  // Added at session end:
  "end_time": "2026-05-29T10:15:42Z",
  "duration_s": 2484,
  "total_turns": 23,
  "total_tokens": 148920,
  "tools_used": ["Bash", "ReadFile", "WriteFile"],
  "errors": 0
}

events.jsonl Example

{"ts":"2026-05-29T09:34:18Z","event":"session_start","data":{"model":"opus","provider":"claude_code"}}
{"ts":"2026-05-29T09:34:20Z","event":"tool_use","data":{"tool":"Bash","id":"toolu_01abc"}}
{"ts":"2026-05-29T09:34:22Z","event":"api_response","data":{"tokens":1423,"latency_ms":1847}}
{"ts":"2026-05-29T10:15:42Z","event":"session_end","data":{"duration_s":2484,"turns":23}}

CLI & Tools

ScorpioX Code includes dedicated binaries for session management, all compiled from C source:

scorpiox-emit-session Flags

scorpiox-emit-session \
  --session session_1716940000 \  # Session ID (required)
  --seq 5 \                      # Message sequence number
  --type tool_result \           # Message type
  --text "exit code: 0" \        # Message text (inline)
  --provider claude_code \       # Provider name
  --model opus \                 # Model name
  --project myproject \          # Project name (default: basename of cwd)
  --branch main                   # Git branch (default: auto-detect)

Listing Sessions with sx

# Start a new session
sx

# Resume with a specific session ID
sx --session-id session_1716940000

# Start fresh (ignores previous session)
sx --new

# Emit session telemetry externally
sx --emit-session https://telemetry.example.com/v1/events

Configuration

Session behavior is controlled by these keys in scorpiox-env.txt:

Example Configuration

# scorpiox-env.txt — session settings
SESSION_RETENTION_DAYS=30
LOG_LEVEL=DEBUG
LOG_DIR=/var/log/scorpiox
AGENT_MAX_RECURSION_DEPTH=5
BASH_DEFAULT_TIMEOUT=60000
ASKUSER_TIMEOUT=300
AUTO_ACCEPT_PLAN=0

Session Hooks

Three lifecycle hooks fire at session boundaries. Place shell scripts in .scorpiox/hooks/<hook_name>/ to extend session behavior.

Hook Script Example

#!/bin/bash
# .scorpiox/hooks/session_start/01-notify.sh
# Notify when a new session starts

SESSION_ID="$2"
TIMESTAMP="$3"
JSON_DATA="$4"

MODEL=$(echo "$JSON_DATA" | jq -r .model)
echo "Session $SESSION_ID started at $TIMESTAMP with model $MODEL" >> /tmp/sx.log

# For blocking hooks, prefix with sync-:
# .scorpiox/hooks/session_start/sync-01-validate.sh

Resuming Sessions

Sessions can be resumed by passing the session ID to sx. The conversation history is loaded from conversation.json and the session continues where it left off.

# Resume a specific session
sx --session-id session_1716940000

# The conversation is loaded from:
# .scorpiox/sessions/session_1716940000/conversation.json

# The conversation.json schema:
# JSON array of message objects with fields:
#   role: user | assistant | tool_use | tool_result
#   content: message text
#   tool_id, tool_name, tool_input: for tool calls
#   thinking, thinking_sig: for extended thinking blocks
#   timestamp_ms: millisecond timestamp

The scorpiox-rewind tool can restore previous conversation states. It reads the conversation history and allows you to jump back to an earlier turn, effectively undoing tool executions and assistant responses.

# Rewind to a previous state
scorpiox-rewind --help

# View a session transcript interactively
scorpiox-transcript

Retention & Cleanup

Sessions are retained for SESSION_RETENTION_DAYS (default: 7 days). The cleanup logic lives in libsxutil/sx_config.c and the sx main binary.

# Keep sessions for 30 days instead of 7
SESSION_RETENTION_DAYS=30

# Disable automatic cleanup entirely
SESSION_RETENTION_DAYS=0

# Session data stored per session (typical):
#   meta.json            ~500 bytes
#   conversation.json    10-500 KB (depends on session length)
#   config-snapshot.txt  ~4 KB
#   session.log          5-50 KB
#   agent.log            2-20 KB
#   events.jsonl         1-10 KB
#   trace.jsonl          1-5 KB
#   traffic/raw/         50-500 KB (API bodies)