scorpiox-emit-session

Overview

scorpiox-emit-session is a lightweight telemetry client that ships session event data to a remote endpoint via HTTPS POST. It is compiled as part of the scorpiox code toolchain and runs in fire-and-forget mode — it posts the payload and exits immediately without waiting for a response body.

The client automatically collects machine metadata (hostname, OS, architecture), detects the current git branch and project name, and attaches it to every event. This enables centralized session analytics without any manual instrumentation.

Source: scorpiox/scorpiox-emit-session.c — compiled to a static binary with zero runtime dependencies.

How It Works

When session tracking is enabled, the main sx process invokes scorpiox-emit-session as a subprocess after each conversation turn. The telemetry client receives event data either as command-line arguments or via file-based input for large content payloads.

Lifecycle

1. sx.c checks EMIT_SESSION_TRACKING=1 in scorpiox-env.txt
2. On each conversation turn, sx.c forks scorpiox-emit-session
3. The client collects machine metadata (hostname, OS, arch) automatically
4. It detects the current git branch and project name from the working directory
5. Constructs a JSON payload with the message type, content, and metadata
6. Sends a single HTTPS POST to the configured EMIT_SESSION_API_URL
7. Exits immediately — does not block the main session

Fire-and-Forget Design

The client is designed to never delay the user's workflow. It runs as a detached subprocess, sends the POST request, and terminates. Network failures are silently ignored — telemetry is best-effort, never critical path.

Configuration

Configure session emission via scorpiox-env.txt in your project root or ~/.scorpiox-env.txt globally.

# Enable session telemetry
EMIT_SESSION_TRACKING=1

# Set your analytics endpoint
EMIT_SESSION_API_URL=https://analytics.example.com/api/sessions

Message Types

Each event sent by scorpiox-emit-session includes a message type that categorizes the conversation turn. The following types are supported:

For large content (e.g., full assistant responses), sx.c writes the content to a temporary file and passes the path to scorpiox-emit-session via the --file flag. The client reads the file, includes it in the JSON payload, and the file is cleaned up after transmission.

Features

Usage Examples

Enable Session Tracking

# Add to your project's scorpiox-env.txt
echo "EMIT_SESSION_TRACKING=1" >> scorpiox-env.txt
echo "EMIT_SESSION_API_URL=https://your-api.example.com/sessions" >> scorpiox-env.txt

Direct Invocation (Testing)

# Send a test event directly
scorpiox-emit-session --type user --content "Hello, world"

# Send large content via file
scorpiox-emit-session --type assistant --file /tmp/response.txt

# Check that the binary is available
which scorpiox-emit-session

JSON Payload Structure

{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "user",
  "content": "Explain the networking stack",
  "timestamp": "2026-03-13T15:43:21+13:00",
  "metadata": {
    "hostname": "dev-machine",
    "os": "linux",
    "arch": "x86_64",
    "git_branch": "main",
    "project": "my-project"
  }
}

Architecture

scorpiox-emit-session is compiled from scorpiox/scorpiox-emit-session.c as a standalone static binary. It links against the system TLS stack for HTTPS and uses POSIX sockets for the actual network I/O. No external libraries (no curl, no OpenSSL dependency at the application layer).

Integration with sx.c

The main scorpiox binary (sx.c) manages the lifecycle:

• Reads EMIT_SESSION_TRACKING from config at startup
• Maintains a session ID for the duration of the interactive session
• After each turn, forks scorpiox-emit-session with the event data
• The child process is fully detached — sx.c does not wait on it

Security

All data is transmitted over HTTPS (port 443). The endpoint URL is user-configured — no data is sent anywhere unless you explicitly set EMIT_SESSION_API_URL. Session tracking is disabled by default (EMIT_SESSION_TRACKING=0).

Network Reference

scorpiox-emit-session is one of 15 networking components in the scorpiox code toolchain. Here's how it fits alongside the other network tools: