Sessions

Overview

Every ScorpioX Code invocation runs inside a session — an isolated workspace that tracks the conversation, logs, configuration snapshot, API traffic, and event history. Sessions are persisted to .scorpiox/sessions/<id>/ and can be resumed, rewound, or inspected after the fact.

The session subsystem is implemented in sx_session.c / sx_session.h within libsxutil (23,736 LOC). It handles session creation, directory setup, conversation persistence (via sx_conv_save / sx_conv_load), config snapshot capture, and lifecycle hook firing.

Sessions are identified by a unique ID generated at startup. The ID is used as the directory name under .scorpiox/sessions/ and passed to hooks via $2. Set SESSION_RETENTION_DAYS in scorpiox-env.txt to control automatic cleanup (default: 7 days).

Session Lifecycle

A session progresses through well-defined stages. Hooks fire at each transition, allowing shell scripts to react to lifecycle events.

🚀 Start

sx_session_init()

→

📋 Config Snapshot

config-snapshot.txt

→

🔄 session_start hook

.scorpiox/hooks/session_start/

→

💬 Conversation Loop

user → model → tools

→

💾 Auto-save

conversation.json

→

🏁 session_end hook

.scorpiox/hooks/session_end/

During the conversation loop, the conversation is saved after every model turn via sx_conv_save_to_path_dual. If the user runs /clear, the session_clear hook fires and the conversation resets while keeping the same session directory. Conversation compaction triggers the compact hook.

Session Directory Structure

Each session creates a self-contained directory under .scorpiox/sessions/:

.scorpiox/sessions/<session-id>/
├── conversation.json     # Full message history
├── session.log            # Debug/info/error log
├── agent.log              # Agent-level operations log
├── events.jsonl           # Structured event stream
├── trace.jsonl            # Data flow trace
├── config-snapshot.txt    # Config at session start
└── traffic/
    └── traffic.log        # API round-trip log

Legacy sessions stored conversations at .scorpiox/conversations/<id>.json. The current layout co-locates all session artifacts in one directory for easier cleanup and archival.

Configuration

Session behavior is controlled via scorpiox-env.txt configuration keys. These are read at session start and frozen in config-snapshot.txt.

Key	Default	Type	Description
`AGENTLESS_MODE`	`0`	boolean	Run in agentless mode (no sub-agents)
`AGENT_MAX_RECURSION_DEPTH`	`10`	integer	Maximum recursion depth for nested agent calls
`ASKUSER_TIMEOUT`	`120`	string	Timeout in seconds for AskUserQuestion prompts
`AUTO_ACCEPT_PLAN`	`1`	boolean	Auto-accept plans without user confirmation
`BASH_DEFAULT_TIMEOUT`	`30000`	string	Default timeout in ms for Bash tool execution
`BASH_MIN_TIMEOUT`	`0`	string	Minimum timeout in ms for Bash tool (0 = no minimum)
`LOG_DIR`	`.scorpiox/logs`	string	Directory for session logs
`LOG_LEVEL`	`INFO`	string	Logging verbosity level (DEBUG, INFO, WARN, ERROR, TRACE)
`PROJECT_DIR`	`""`	string	Project directory override for CLAUDE.md search
`SESSION_RETENTION_DAYS`	`7`	string	Days to retain session logs
`EMIT_SESSION_API_URL`	`""`	string	API endpoint for session event data
`EMIT_SESSION_TRACKING`	`0`	boolean	Enable session event emission

# Example scorpiox-env.txt session settings
SESSION_RETENTION_DAYS=14
LOG_LEVEL=DEBUG
BASH_DEFAULT_TIMEOUT=60000
AGENTLESS_MODE=0
EMIT_SESSION_TRACKING=1
EMIT_SESSION_API_URL=https://analytics.example.com/v1/sessions

Session Tools

ScorpioX Code ships dedicated binaries for session management — conversation handling, event emission, history rewind, and transcript viewing.

Tool	Description	Source	Size
`scorpiox-conv`	Conversation manager for AI sessions	`scorpiox-conv.c`	253 LOC
`scorpiox-emit-session`	Session event telemetry emitter	`scorpiox-emit-session.c`	590 LOC
`scorpiox-rewind`	Conversation rewind tool for restoring previous states	`scorpiox-rewind.c`	624 LOC
`scorpiox-transcript`	Transcript viewer TUI with terminal rendering	`scorpiox-transcript.c`	731 LOC

scorpiox-emit-session flags

scorpiox-emit-session \
  --session <session-id>     # Session ID (required)
  --seq <number>             # Message sequence number
  --type <msg-type>          # user, assistant, tool_call, tool_result
  --text <content>           # Message text (inline)
  --file <path>              # Read message from file (large content)
  --provider <name>          # Provider name
  --model <name>             # Model name
  --project <name>           # Project name (default: basename of cwd)
  --branch <name>            # Git branch (default: auto-detect)

Resume Picker TUI

The sxui_resume component (in libsxui) renders an interactive overlay listing previous conversations with relative timestamps. Navigate with arrow keys or mouse, press Enter to resume. The picker supports drag-to-move positioning.

Session Hooks

Session lifecycle hooks let you run shell scripts at key moments. Place executable scripts in .scorpiox/hooks/<hook_name>/ — they run asynchronously unless prefixed with sync-.

Hook	Type	Trigger	Location
`session_start`	lifecycle	New session begins (model, provider, log_level available in JSON data)	`.scorpiox/hooks/session_start/`
`session_end`	lifecycle	Session ends gracefully	`.scorpiox/hooks/session_end/`
`session_clear`	lifecycle	User runs /clear command	`.scorpiox/hooks/session_clear/`
`compact`	event	Conversation compacted (from, to message counts in JSON data)	`.scorpiox/hooks/compact/`

# Example: notify on session start
mkdir -p .scorpiox/hooks/session_start
cat > .scorpiox/hooks/session_start/01-notify.sh << 'EOF'
#!/bin/bash
# $1 = hook name, $2 = session ID, $3 = timestamp, $4 = JSON data
MODEL=$( echo "$4" | jq -r .model )
echo "Session $2 started with $MODEL" >> /tmp/sx-sessions.log
EOF
chmod +x .scorpiox/hooks/session_start/01-notify.sh

Hook scripts receive 4 arguments: $1 = hook name, $2 = session ID, $3 = ISO timestamp, $4 = JSON payload with context data. Prefix script names with sync- to make them blocking (e.g., sync-01-validate.sh).

Session Files

Each session produces structured files for conversation history, logging, tracing, and debugging.

File	Location	Purpose
`conversation.json`	`.scorpiox/sessions/<id>/`	Full conversation history — messages, tool calls, thinking blocks
`session.log`	`.scorpiox/sessions/<id>/`	Session-scoped debug/info/error log with millisecond timestamps
`agent.log`	`.scorpiox/sessions/<id>/`	Agent-level logging of API requests and tool results
`events.jsonl`	`.scorpiox/sessions/<id>/`	Structured event log — session_start, tool_use, api_response, etc.
`trace.jsonl`	`.scorpiox/sessions/<id>/`	Data flow trace for debugging tool_use parsing and API calls
`config-snapshot.txt`	`.scorpiox/sessions/<id>/`	Frozen copy of all resolved config key-value pairs at session start
`traffic.log`	`.scorpiox/sessions/<id>/traffic/`	Append-only summary of all API round-trips with status codes

conversation.json schema

// JSON array of message objects
[
  {
    "role": "user",
    "content": "hello",
    "timestamp_ms": 1716940000000
  },
  {
    "role": "assistant",
    "content": "Hi! How can I help?",
    "thinking": "...",
    "timestamp_ms": 1716940001000
  },
  {
    "role": "tool_use",
    "tool_id": "toolu_01abc",
    "tool_name": "Bash",
    "tool_input": { "command": "ls -la" }
  }
]

events.jsonl format

// One JSON object per line
{"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:35:01Z","event":"api_response","data":{"status":200,"bytes":4821}}

Resuming Sessions

ScorpioX Code supports resuming previous sessions. The conversation history is loaded from conversation.json and the model continues where you left off.

# Resume via the TUI resume picker
sx                            # Launch normally, press the resume shortcut

# Resume a specific session by ID
sx --resume <session-id>

# Use scorpiox-rewind to roll back to a previous state
scorpiox-rewind --help

The resume picker (sxui_resume.c) displays a list of recent sessions with relative timestamps (e.g., "2 hours ago"). It supports keyboard navigation (up/down/page up/page down) and mouse selection.

scorpiox-rewind (624 LOC) lets you roll back the conversation to an earlier point, removing tool calls or model responses that went wrong. It operates on conversation.json and creates a backup before modifying.

Session Tracking & Telemetry

Session telemetry can be enabled to emit conversation events to an external API. This powers dashboards, analytics, and audit trails.

# Enable session tracking in scorpiox-env.txt
EMIT_SESSION_TRACKING=1
EMIT_SESSION_API_URL=https://your-api.example.com/v1/events

When enabled, scorpiox-emit-session sends structured events to the configured endpoint. Each event includes the session ID, sequence number, message type, provider, model, project name, and git branch. The --headless flag implies --emit-session for SDK and automation use cases.

Headless mode (sx --headless) disables the TUI and emits session message files (msg_NNNN_type.txt) for SDK consumption. It automatically enables session tracking. Used by daemon servers and automated pipelines.

Contents

Overview

Session Lifecycle

Session Directory Structure

Configuration

Session Tools

scorpiox-emit-session flags

Resume Picker TUI

Session Hooks

Session Files

conversation.json schema

events.jsonl format

Resuming Sessions

Session Tracking & Telemetry