Usage Send — SCORPIOX CODE

Overview

scorpiox-usage is a standalone binary that sends token usage data to a remote API endpoint after each AI provider response. It runs as a fire-and-forget process — the main agent spawns it in the background so usage reporting never blocks the conversation loop.

When USAGE_TRACKING=1 is set in scorpiox-env.txt, the agent automatically invokes scorpiox-usage after every API response with the input/output token counts, model name, provider, session ID, project, and git branch. The binary constructs a JSON payload and POSTs it to the configured USAGE_API_URL.

Dependencies: libcurl, libsxhttp, libsxutil. Available on all platforms: linux-x64, linux-arm64, macos-arm64, windows-x64.

How It Works

1. API Response Received

The agent (sx_agent.c) receives a response from the AI provider with token counts and stop reason.

2. Check USAGE_TRACKING

If USAGE_TRACKING=1 in config, the agent spawns scorpiox-usage as a background process.

3. Build JSON Payload

The binary assembles a JSON object with session, provider, model, input/output tokens, tier, project, and branch.

4. HTTP POST

Uses libcurl to POST the JSON payload to USAGE_API_URL. Logs success or failure to stderr.

5. Exit

Process exits with code 0 on success. Non-zero exit codes indicate payload or network errors.

CLI Flags

Flag	Short	Description
`--session`	`-s`	Session ID (required)
`--provider`	`-p`	Provider: claude, gemini, openai (required)
`--model`	`-m`	Model name (sonnet-4, opus-4, etc.)
`--input`	`-i`	Input tokens
`--output`	`-o`	Output tokens
`--tier`	`-t`	Service tier (standard, priority)
`--project`	—	Project name (default: basename of cwd)
`--branch`	—	Git branch (default: auto-detect)

Example invocation

# Typical call from the agent after an API response
scorpiox-usage   --session abc123-def456   --provider claude   --model sonnet-4   --input 12450   --output 3820   --tier standard   --project my-app   --branch main

Configuration

Set these keys in scorpiox-env.txt (project-level or global). The agent reads them at session start and passes relevant values when spawning scorpiox-usage.

Key	Default	Description
`USAGE_TRACKING`	`0`	Enable usage/telemetry tracking (0 or 1)
`USAGE_API_URL`	(empty)	API endpoint for usage tracking data
`EMIT_SESSION_TRACKING`	`0`	Enable session event emission (0 or 1)
`EMIT_SESSION_API_URL`	(empty)	API endpoint for session event data
`CONTEXT_WARN_THRESHOLD`	`80`	Percentage threshold to warn about context usage

scorpiox-env.txt

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

# Optional: also emit session events
EMIT_SESSION_TRACKING=1
EMIT_SESSION_API_URL=https://telemetry.example.com/v1/sessions

# Warn when context hits 80%
CONTEXT_WARN_THRESHOLD=80

API Payload

The JSON payload POSTed to USAGE_API_URL contains these fields. Content-Type is application/json.

session string — unique session identifier

provider string — "claude", "gemini", or "openai"

model string — model name (e.g. "sonnet-4")

input_tokens integer — input token count for this turn

output_tokens integer — output token count for this turn

tier string — "standard" or "priority"

project string — project directory name

branch string — current git branch

Example payload

{
  "session": "abc123-def456",
  "provider": "claude",
  "model": "sonnet-4",
  "input_tokens": 12450,
  "output_tokens": 3820,
  "tier": "standard",
  "project": "my-app",
  "branch": "main"
}

Examples

Manual test — send usage for a Claude session

scorpiox-usage   -s test-session-001   -p claude   -m opus-4   -i 50000   -o 15000   -t priority

Gemini usage with auto-detected project and branch

# Project and branch auto-detect from cwd and git
scorpiox-usage   --session sess-77f2a   --provider gemini   --model gemini-2.5-pro   --input 8200   --output 2100

OpenAI Codex usage

scorpiox-usage   -s codex-run-42   -p openai   -m codex-mini   -i 6000   -o 1200   -t standard   --project backend-api   --branch feature/auth

Hook Integration

The api_response hook fires after every AI provider response. You can use it to build custom usage dashboards, trigger alerts on high token consumption, or forward data to third-party analytics.

.scorpiox/hooks/api_response/log-tokens.sh

#!/bin/bash
# $4 contains JSON with in_tokens, out_tokens, stop_reason
IN=$( echo $4 | jq -r .in_tokens )
OUT=$( echo $4 | jq -r .out_tokens )
echo "$(date -Iseconds) in=$IN out=$OUT" >> /tmp/token-usage.log

The hook receives the session ID as $1, turn number as $2, content count as $3, and a JSON blob as $4 containing in_tokens, out_tokens, and stop_reason.

Error Handling

All errors are logged to stderr. The binary exits with code 1 on any failure. These are the error messages you may encounter:

Error: --session is required

Pass a session ID via -s or --session.

Error: --provider is required

Specify the AI provider: claude, gemini, or openai.

usage: JSON payload too large

The assembled JSON exceeds the internal buffer. Check argument lengths.

usage: POST failed: <curl error>

Network error. Check USAGE_API_URL is reachable and the endpoint is up.

usage: POST HTTP <status>: <body>

The API returned a non-2xx status. Check the endpoint accepts the payload format.