Real-time token usage tracking with stacked history bars, per-turn breakdowns, session analytics, and API cost visibility — all rendered in the TUI status bar.
scorpiox code tracks every API token consumed across all providers in real time. The 5-line status bar at the bottom of the TUI displays a stacked usage history chart with color-coded breakdowns of input tokens, output tokens, cache reads, and cache writes — updated after every API response.
Two dedicated tools — scorpiox-usage and
scorpiox-emit-session — provide API usage
aggregation and session event emission for external analytics pipelines. Combined
with lifecycle hooks (api_response,
session_end,
agent_complete), you get full visibility
into token consumption without any third-party dependencies.
The status bar occupies the bottom 5 lines of the terminal. Line 1 shows a stacked horizontal bar chart of token usage history — each turn is a vertical slice with segments proportional to token type. Lines 2-5 display the model name, working directory with git branch, cache keep-alive timer, and background task indicators.
| Token Type | Color | Hex |
|---|---|---|
| input_tokens | Gray | 0x888888 |
| output_tokens | Cyan | 0x00AAFF |
| cache_read | Green | 0x00FF00 |
| cache_write | Orange | 0xFFAA00 |
| total | Light Gray | 0xCCCCCC |
The status bar includes a countdown timer showing time until the prompt cache expires. Color indicates urgency:
| State | Color | Condition |
|---|---|---|
| fresh | Green | > 3 minutes remaining |
| warning | Yellow | 1–3 minutes remaining |
| urgent | Red | < 1 minute remaining |
A background thread (cache_keepalive) auto-sends
keepalive messages at ~4:30 of idle time to maintain the Claude prompt cache,
reducing cache_write tokens on subsequent turns.
Every API response includes token counts that scorpiox code parses and accumulates.
The api_response hook fires after each response
with structured JSON data including turn number, content count, stop reason,
input tokens, and output tokens.
Each API turn records the following token metrics, available via hooks and the info box overlay:
Prompt tokens sent to the API — system prompt, conversation history, tool results. Shown in gray (0x888888) in the status bar.
Response tokens generated by the model — assistant messages, tool calls, thinking. Shown in cyan (0x00AAFF) in the status bar.
Tokens served from the prompt cache instead of reprocessing. Shown in green (0x00FF00) — higher is better (cheaper).
Tokens written into the prompt cache for future reuse. Shown in orange (0xFFAA00) — initial cost, pays off over turns.
scorpiox code monitors cumulative token usage against configurable thresholds to prevent runaway costs and context overflow:
# Warn when context reaches this percentage of the limit CONTEXT_WARN_THRESHOLD=80 # Auto-clear context when token count exceeds this CONTEXT_CLEAR_THRESHOLD=190000 # Enable automatic context compaction CONTEXT_AUTO_COMPACT=1 # Token budget for extended thinking THINKING_BUDGET=10000
When CONTEXT_WARN_THRESHOLD is reached,
the status bar displays a visual warning. At
CONTEXT_CLEAR_THRESHOLD, the context is
automatically cleared or compacted (if CONTEXT_AUTO_COMPACT
is enabled), firing the compact hook with
before/after message counts.
Usage tracking is configured through scorpiox-env.txt.
All settings are optional — the status bar token display is always active.
| Key | Default | Description |
|---|---|---|
| USAGE_TRACKING | 0 | Enable usage/telemetry tracking to external endpoint |
| USAGE_API_URL | (empty) | API endpoint for usage tracking data |
| EMIT_SESSION_TRACKING | 0 | Enable session event emission |
| EMIT_SESSION_API_URL | (empty) | API endpoint for session event data |
| CONTEXT_WARN_THRESHOLD | 80 | Percentage threshold to warn about context usage |
| CONTEXT_CLEAR_THRESHOLD | 190000 | Token threshold to trigger context clear |
| CONTEXT_AUTO_COMPACT | 1 | Enable automatic context compaction |
| THINKING_BUDGET | 10000 | Token budget for extended thinking |
# scorpiox-env.txt USAGE_TRACKING=1 USAGE_API_URL=https://analytics.example.com/v1/usage # Also emit session lifecycle events EMIT_SESSION_TRACKING=1 EMIT_SESSION_API_URL=https://analytics.example.com/v1/sessions
scorpiox code fires shell script hooks at key lifecycle points, letting you
build custom usage dashboards, alerts, or cost tracking without modifying the core.
Place executable scripts in .scorpiox/hooks/<hook_name>/.
| Hook | Trigger | Data |
|---|---|---|
| api_response | After each API response | turn, content_count, stop_reason, in_tokens, out_tokens |
| session_start | New session begins | model, provider, log_level |
| session_end | Session ends gracefully | Session ID, duration |
| agent_complete | Agent finishes a run | turns, history_count |
| subagent_complete | Sub-agent finishes | turns, history_count |
| compact | Context compacted | from_count, to_count |
| session_clear | User runs /clear | Session ID |
#!/bin/bash # $1 = hook name, $2 = JSON data DATA="$2" TURN=$(echo "$DATA" | jq -r '.turn') IN=$(echo "$DATA" | jq -r '.in_tokens') OUT=$(echo "$DATA" | jq -r '.out_tokens') echo "$(date -Iseconds) turn=$TURN in=$IN out=$OUT" >> ~/.scorpiox/usage.log
scorpiox code supports 8 providers, each with its own token counting and authentication flow. The usage dashboard tracks tokens uniformly across all backends through the common agent layer.
| Provider | Token Source | Models |
|---|---|---|
| claude_code | local, http, ssh, tcp | opus, sonnet, haiku |
| codex | tcp | gpt-5.5, gpt-5.4, gpt-5.4-mini |
| scorpiox | Router (scorpiox.net:5175) | opus, sonnet, haiku |
| gemini | remote | Configurable via GEMINI_MODEL |
| openai | Bearer token | Configurable via OPENAI_MODEL |
Token fetching is handled by dedicated binaries
(scorpiox-claudecode-fetchtoken,
scorpiox-codex-fetchtoken) with configurable
sources. The FETCHTOKEN_LISTEN_PORT (default: 9800)
runs a local server for token distribution across concurrent sessions.
USAGE_API_URL
endpoint. Runs as a standalone static binary.
EMIT_SESSION_API_URL.
Enables external dashboards and billing integration.
#!/bin/bash # .scorpiox/hooks/session_end/report.sh # Summarize session usage on exit SESSION_ID="$2" LOG=~/.scorpiox/usage.log echo "=== Session $SESSION_ID Summary ===" grep "$SESSION_ID" "$LOG" | awk -F'[= ]' '{ in_total += $4; out_total += $6 } END { printf "Input tokens: %d\n", in_total printf "Output tokens: %d\n", out_total printf "Total tokens: %d\n", in_total + out_total }'