Sessions & Query

Overview

scorpiox-host is a session gateway server written in pure C (1,882 lines). It tracks active AI coding sessions, stores events in a per-session ring buffer, and provides a message queue for inter-process communication. The server runs on port 7432 and requires no external dependencies.

scorpiox-host

Session gateway server — tracks AI agent sessions, events, and messages over REST API. Features: session_tracking, event_ring_buffer, message_queue, session_discovery, daemon_mode. Source: scorpiox/scorpiox-host.c

scorpiox-emit-session

Session event telemetry emitter (590 lines). Sends structured session events to a remote API endpoint. Supports message types: user, assistant, tool_call, tool_result. Source: scorpiox/scorpiox-emit-session.c

API Endpoints

All endpoints are served by scorpiox-host on port 7432. No authentication required. Responses are JSON.

Method	Path	Description
GET	`/status`	Server summary — returns version, port, uptime, session count, active count, and total events
GET	`/sessions`	List all sessions — JSON array with id, state, last_event timestamp, event_count, and optional model/provider metadata
GET	`/sessions/:id`	Session detail — full session info including discovered time, state, event count, recent events (last 10), model, provider, cwd, start_time
GET	`/sessions/:id/events`	Get session events — returns recent events as NDJSON (newline-delimited JSON)
POST	`/sessions/:id/events`	Fire session event — pushes an event to the session's ring buffer. Supported types: thinking, tool-start, tool-done, complete, error, idle, user-message, compact
POST	`/sessions/:id/register`	Register a session — creates or updates a session with a display name, sets state to idle
GET	`/sessions/:id/messages`	Pull queued messages — returns and drains the message queue for a session
POST	`/sessions/:id/messages`	Queue a message — pushes a message to the session's queue (max 32 messages, max 8KB each). Returns 429 if queue full

Example: List Sessions

# Query all active sessions
curl http://localhost:7432/sessions | jq .

# Response
[
  {
    "id": "abc123",
    "state": "idle",
    "last_event": "2026-05-28T21:45:00Z",
    "event_count": 47,
    "model": "opus",
    "provider": "claude_code"
  }
]

Example: Session Detail

# Get full session info
curl http://localhost:7432/sessions/abc123 | jq .

# Response includes recent events, metadata, working directory
{
  "id": "abc123",
  "state": "idle",
  "discovered": "2026-05-28T20:00:00Z",
  "event_count": 47,
  "model": "opus",
  "provider": "claude_code",
  "cwd": "/workspace/project",
  "recent_events": [...]
}

Event System

Events are stored in a per-session ring buffer. Each session maintains its own event history. Events are returned as NDJSON when querying GET /sessions/:id/events.

Supported Event Types

thinking

Agent is processing — model is generating a response

tool-start

Tool invocation begins — Bash, ReadFile, etc.

tool-done

Tool invocation completed with result

complete

Agent turn finished — task completed

error

Error occurred during processing

idle

Session is idle — waiting for input

user-message

User sent a message to the session

compact

Context window compacted to save tokens

Fire an Event

# Push a tool-start event
curl -X POST http://localhost:7432/sessions/abc123/events \
  -H "Content-Type: application/json" \
  -d '{"event":"tool-start","data":"Bash: git status"}'

# Response
{ "ok": true }

Message Queue

Each session has a message queue for inter-process communication. Messages are capped at 32 per queue with a maximum size of 8KB each. Pulling messages drains the queue.

Queue Limits

Max messages per session: 32 · Max message size: 8,192 bytes · HTTP 429 returned if queue is full.

Send a Message

# Queue a message to a session
curl -X POST http://localhost:7432/sessions/abc123/messages \
  -H "Content-Type: application/json" \
  -d '{"message":"Please run the test suite next"}'

Pull Messages

# Drain the message queue
curl http://localhost:7432/sessions/abc123/messages | jq .

# Returns array of queued messages, then empties the queue
["Please run the test suite next"]

Session Telemetry

scorpiox-emit-session is a standalone binary (590 lines of C) that sends structured session events to a remote API endpoint. It's invoked by the main sx process when EMIT_SESSION_TRACKING=1 is set in scorpiox-env.txt.

CLI Flags

Flag	Short	Description
--session	-s	Session ID (required)
--seq	—	Message sequence number
--type	—	Message type: user, assistant, tool_call, tool_result
--text	—	Message text (inline)
--file	—	Read message text from file (for large content)
--provider	—	Provider name (e.g., claude_code)
--model	—	Model name (e.g., opus)
--project	—	Project name (default: basename of cwd)
--branch	—	Git branch (default: auto-detect)

Example

# Emit a tool_call event
scorpiox-emit-session \
  --session abc123 \
  --seq 5 \
  --type tool_call \
  --text "Bash: git diff HEAD~1" \
  --provider claude_code \
  --model opus

Configuration

Session-related keys in scorpiox-env.txt. These control session behavior, logging, timeouts, and telemetry emission.

Session Category

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: 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

Usage / Telemetry Category

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

CLI Usage

scorpiox-host operates as both a server and CLI client.

Start the Server

# Start in daemon mode on default port 7432
scorpiox-host --daemon

# Start on a custom port
scorpiox-host --daemon --port 9000

# Follow live events from all sessions
scorpiox-host --follow

Register a Session

# Register a new session with a display name
curl -X POST http://localhost:7432/sessions/my-session/register \
  -H "Content-Type: application/json" \
  -d '{"session":"Feature Branch Work"}'

# Response
{ "ok": true, "id": "my-session" }

Server Status

# Check server health
curl http://localhost:7432/status | jq .

# Response
{
  "version": "1.0",
  "port": 7432,
  "uptime": 3600,
  "sessions": 3,
  "active": 1,
  "total_events": 284
}

scorpiox-env.txt Example

# Enable session tracking and telemetry
EMIT_SESSION_TRACKING=1
EMIT_SESSION_API_URL=https://api.scorpiox.net/sessions

# Session retention
SESSION_RETENTION_DAYS=14
LOG_LEVEL=DEBUG
LOG_DIR=.scorpiox/logs

# Agent settings
AGENT_MAX_RECURSION_DEPTH=5
BASH_DEFAULT_TIMEOUT=60000
ASKUSER_TIMEOUT=300

Contents