Sessions Dashboard — SCORPIOX CODE

Overview

Every ScorpioX Code conversation is a session. Sessions are managed by sx_session.c in libsxutil, providing persistence, structured event logging, and hook-based extensibility. Sessions are stored on disk as directories under .scorpiox/sessions/<id>/, each containing conversation state, event logs, and metadata.

The session system integrates with the TUI resume picker (sxui_resume in libsxui) for selecting and continuing previous sessions, and with scorpiox-tmux for terminal multiplexer session management.

Session Lifecycle

A session moves through well-defined stages. Each transition fires the corresponding hook, allowing you to inject custom logic at every step.

🚀

session_start

Init model, provider,
log level

→

💬

active

Conversation loop,
tool calls, agents

→

🔄

session_clear

/clear resets
conversation

→

💬

active

New conversation
continues

→

🏁

session_end

Graceful shutdown,
logs flushed

Agent recursion within a session is bounded by AGENT_MAX_RECURSION_DEPTH (default: 10). Each sub-agent invocation increments the depth counter, preventing runaway nested calls.

Session Storage

Session data is stored on disk in the project's .scorpiox/ directory. Each session gets a unique ID-based directory:

.scorpiox/ ├── sessions/ │ ├── <session-id>/ │ │ ├── events.jsonl # structured event log (one JSON per line) │ │ ├── msg_0001_event.json # per-message event file (when emit_msg enabled) │ │ ├── msg_0002_event.json │ │ └── ... │ └── <session-id-2>/ │ └── ... ├── logs/ # LOG_DIR — rotating log files │ ├── scorpiox.log │ └── scorpiox.log.1 └── hooks/ # hook scripts ├── session_start/ ├── session_end/ └── session_clear/

Events are written as JSONL (JSON Lines) to events.jsonl via sx_session_event(). When EMIT_SESSION_TRACKING is enabled, events are also emitted as individual msg_NNNN_event.json files for SDK consumers.

Configuration

All session settings are configured via scorpiox-env.txt in your project root or ~/.scorpiox/. These keys control session behavior, timeouts, and logging.

Key	Default	Description	Source
`AGENTLESS_MODE`	`0`	Run in agentless mode (no sub-agents)	`sx_config.c`
`AGENT_MAX_RECURSION_DEPTH`	`10`	Maximum recursion depth for nested agent calls	`sx_agent.c`
`ASKUSER_TIMEOUT`	`120`	Timeout in seconds for AskUserQuestion prompts	`sx_agent.c`
`AUTO_ACCEPT_PLAN`	`1`	Auto-accept plans without user confirmation	`sx_state.c`
`BASH_DEFAULT_TIMEOUT`	`30000`	Default timeout in ms for Bash tool execution	`sx_agent.c`
`BASH_MIN_TIMEOUT`	`0`	Minimum timeout in ms for Bash tool (0 = no minimum)	`sx_agent.c`
`LOG_DIR`	`.scorpiox/logs`	Directory for session logs	`sx_config.c`
`LOG_LEVEL`	`INFO`	Logging verbosity (DEBUG, INFO, WARN, ERROR, TRACE)	`sx_config.c`
`PROJECT_DIR`	`—`	Project directory override for CLAUDE.md search	`scorpiox-email.c`
`SESSION_RETENTION_DAYS`	`7`	Days to retain session logs	`sx_config.c`

scorpiox-env.txt

# Session configuration example
LOG_DIR=.scorpiox/logs
LOG_LEVEL=INFO
SESSION_RETENTION_DAYS=14
AGENT_MAX_RECURSION_DEPTH=5
BASH_DEFAULT_TIMEOUT=60000
ASKUSER_TIMEOUT=300
AUTO_ACCEPT_PLAN=0
        

Session Hooks

Session lifecycle hooks let you run shell scripts at key moments. Place executable scripts in the corresponding .scorpiox/hooks/ subdirectory. Scripts prefixed with sync- run synchronously (blocking); all others run async.

session_start

Fired when a new session begins. JSON data includes model name, provider, and log level.

#!/bin/bash # .scorpiox/hooks/session_start/01-notify.sh echo "Session starting: model=$( echo $4 | jq -r .model )" >> /tmp/sx.log

session_end

Fired when a session ends gracefully. Receives session ID and timestamp.

#!/bin/bash # .scorpiox/hooks/session_end/01-cleanup.sh echo "Session $2 ended at $3" >> /tmp/sx.log # Archive session events tar -czf /backups/session-$2.tar.gz .scorpiox/sessions/$2/

session_clear

Fired when the user runs the /clear command to reset conversation context.

#!/bin/bash # .scorpiox/hooks/session_clear/01-log.sh echo "Chat cleared at $(date)" >> /tmp/sx.log

Event Tracking

When enabled, ScorpioX Code emits structured session events that can be consumed by external systems for analytics, billing, or audit trails.

Emit Configuration

Key	Default	Description
`EMIT_SESSION_API_URL`	`—`	API endpoint for session event data
`EMIT_SESSION_TRACKING`	`0`	Enable session event emission
`USAGE_API_URL`	`—`	API endpoint for usage tracking data
`USAGE_TRACKING`	`0`	Enable usage/telemetry tracking

Event Format (JSONL)

// .scorpiox/sessions/<id>/events.jsonl
{"ts":"2026-05-29T09:15:00Z","event":"session_start","model":"opus","provider":"claude_code"}
{"ts":"2026-05-29T09:15:01Z","event":"tool_call","tool":"Bash","duration_ms":1250}
{"ts":"2026-05-29T09:15:03Z","event":"agent_spawn","depth":1,"task":"parse config"}
{"ts":"2026-05-29T09:16:42Z","event":"session_end","total_turns":12,"duration_s":102}
        

The event function signature in C: sx_session_event(SxSession *s, const char *event, const char *json_fields) — appends a timestamped JSON line to the session's event log.

scorpiox-env.txt

# Enable session event emission
EMIT_SESSION_TRACKING=1
EMIT_SESSION_API_URL=https://analytics.example.com/v1/events

# Enable general usage tracking
USAGE_TRACKING=1
USAGE_API_URL=https://analytics.example.com/v1/usage
        

Session Resume

ScorpioX Code can resume previous sessions via the TUI session picker. The sxui_resume component in libsxui presents a list of recent sessions with metadata (model, timestamp, turn count) and lets you continue where you left off.

# Resume the most recent session
sx --resume

# Resume a specific session by ID
sx --resume abc123def

# List recent sessions
sx --sessions
        

Session retention is controlled by SESSION_RETENTION_DAYS (default: 7). Sessions older than this are automatically cleaned up on next launch.

CLI Reference

Session-related CLI flags and slash commands:

# CLI flags
sx --resume              # Resume last session (TUI picker)
sx --resume <id>         # Resume specific session
sx --sessions            # List recent sessions
sx --agentless           # Start in agentless mode
sx --log-level DEBUG     # Override log level

# Slash commands (during session)
/clear                    # Clear conversation (fires session_clear hook)
/status                   # Show session info (model, turns, uptime)
/compact                  # Compact conversation history
        