Session lifecycle management in ScorpioX Code — from initialization through teardown. Logging, event emission, retention policies, and real-time session tracking.
Every ScorpioX Code interaction runs inside a session — a managed context that
tracks conversation state, tool invocations, agent recursion, and timing. Sessions are implemented
in sx_session.c inside libsxutil,
the core utility library (23,736 lines of C).
A session begins when the user starts sx (the main binary) or when an automation
tool like scorpiox-email or scorpiox-imessage
spawns a new coding task. The session owns the conversation log, manages background tasks, and
fires lifecycle hooks at key moments.
scorpiox-emit-session (590 lines) handles
asynchronous session event emission to external APIs for telemetry and monitoring.
Each session follows a well-defined lifecycle with hook points at every transition:
During the active phase, the session tracks tool calls, background task spawning,
agent recursion depth (capped at AGENT_MAX_RECURSION_DEPTH=10),
and user interactions. The /clear command
triggers the session_clear hook,
resetting conversation state without ending the session.
Session behavior is controlled via scorpiox-env.txt keys. All keys below belong to the session category:
| Key | Type | Default | Description |
|---|---|---|---|
SESSION_RETENTION_DAYS |
string | 7 |
Days to retain session logs |
LOG_DIR |
string | .scorpiox/logs |
Directory for session logs |
LOG_LEVEL |
string | INFO |
Logging verbosity level (DEBUG, INFO, WARN, ERROR, TRACE) |
EMIT_SESSION_TRACKING |
boolean | 0 |
Enable session event emission |
EMIT_SESSION_API_URL |
string | — |
API endpoint for session event data |
AGENTLESS_MODE |
boolean | 0 |
Run in agentless mode (no sub-agents) |
AGENT_MAX_RECURSION_DEPTH |
integer | 10 |
Maximum recursion depth for nested agent calls |
ASKUSER_TIMEOUT |
string | 120 |
Timeout in seconds for AskUserQuestion prompts |
AUTO_ACCEPT_PLAN |
boolean | 1 |
Auto-accept plans without user confirmation |
BASH_DEFAULT_TIMEOUT |
string | 30000 |
Default timeout in ms for Bash tool execution |
BASH_MIN_TIMEOUT |
string | 0 |
Minimum timeout in ms for Bash tool (0 = no minimum) |
PROJECT_DIR |
string | — |
Project directory override for CLAUDE.md search |
Session logs are written to LOG_DIR
(default: .scorpiox/logs/).
Each session creates a JSON log file with a UUID-based filename.
The scorpiox-logger binary (275 lines)
provides a TUI for viewing and searching logs. The scorpiox-printlogs
binary (256 lines) offers plain-text log output.
# In scorpiox-env.txt LOG_LEVEL=INFO # Available levels (ascending verbosity): # ERROR — only errors # WARN — errors + warnings # INFO — default, normal operation # DEBUG — detailed internal state # TRACE — full function-level tracing
Sessions older than SESSION_RETENTION_DAYS
(default: 7) are automatically pruned on startup. This prevents unbounded log growth in
long-running development environments. Set to 0
to disable automatic pruning.
# Keep 30 days of session history SESSION_RETENTION_DAYS=30 # Custom log directory LOG_DIR=/var/log/scorpiox/sessions
When EMIT_SESSION_TRACKING=1, the
scorpiox-emit-session binary
sends session events to the configured API endpoint. This enables external monitoring
dashboards, usage analytics, and audit trails.
# Enable session event tracking EMIT_SESSION_TRACKING=1 EMIT_SESSION_API_URL=https://telemetry.example.com/v1/sessions # Events emitted: # session.start — model, provider, timestamp # session.end — duration, tool_count, token_usage # session.clear — conversation reset # session.error — unhandled errors
EMIT_SESSION_TRACKING=0).
When enabled, only session metadata is sent — no conversation content, code, or file paths are included.
Three lifecycle hooks fire at session boundaries. Place shell scripts in the corresponding
.scorpiox/hooks/ directories.
Scripts prefixed with sync-
run synchronously (blocking); all others run asynchronously.
New session begins (model, provider, log_level available in JSON data)
#!/bin/bash echo "Session starting: model=$( echo $4 | jq -r .model )" >> /tmp/sx.log
Session ends gracefully
#!/bin/bash echo "Session $2 ended at $3" >> /tmp/sx.log
User runs /clear command
#!/bin/bash echo "Chat cleared" >> /tmp/sx.log
# Create a session_start hook that logs to a central file
mkdir -p .scorpiox/hooks/session_start
cat > .scorpiox/hooks/session_start/01-log.sh << 'EOF'
#!/bin/bash
SESSION_ID="$2"
TIMESTAMP="$3"
DATA="$4"
MODEL=$(echo "$DATA" | jq -r '.model // "unknown"')
echo "[$TIMESTAMP] Session $SESSION_ID started (model: $MODEL)" >> ~/.scorpiox/session-audit.log
EOF
chmod +x .scorpiox/hooks/session_start/01-log.sh
# Track session durations with an end hook
mkdir -p .scorpiox/hooks/session_end
cat > .scorpiox/hooks/session_end/01-duration.sh << 'EOF'
#!/bin/bash
SESSION_ID="$2"
TIMESTAMP="$3"
echo "[$TIMESTAMP] Session $SESSION_ID ended" >> ~/.scorpiox/session-audit.log
EOF
chmod +x .scorpiox/hooks/session_end/01-duration.sh
# Run without sub-agents for simple tasks AGENTLESS_MODE=1 # This disables: # - Sub-agent spawning # - Agent recursion depth tracking # - Multi-agent orchestration # Useful for single-shot automation scripts
# Increase Bash timeout for long-running builds BASH_DEFAULT_TIMEOUT=120000 # 2 minutes BASH_MIN_TIMEOUT=5000 # 5 second floor ASKUSER_TIMEOUT=300 # 5 minutes for user prompts