File Formats

Complete reference for all 32 file formats used by scorpiox code — configuration, session data, logs, container images, traffic captures, and SDK message files.

32 formats

5 root directories

UTF-8 encoding

C source — pure C implementation

🔍

Overview Directory Structure Configuration Files Session Files Extensibility Files Traffic Capture Files SDK & Integration Files Container & Runtime Files

Overview

scorpiox code is a pure C AI coding assistant that uses a well-defined set of file formats for configuration, session management, logging, traffic capture, and SDK integration. All files are UTF-8 text unless noted. The configuration cascade flows: defaults → exe_dir → ~/.claude/ → .scorpiox/ → environment variables.

# Configuration cascade order (highest priority last):
1. Compiled defaults (in C source)
2. exe_dir/scorpiox-env.txt        # beside the sx binary
3. ~/.claude/scorpiox-env.txt      # user-level
4. .scorpiox/scorpiox-env.txt      # project-level
5. OS environment variables        # override everything

Directory Structure

📁 ~/.scorpiox/

📄 scorpiox-env.txt — User-level configuration (cascade tier: global)

📄 images/ — Container image tarballs (scorpiox-unshare)

📄 rootfs/ — Extracted container root filesystems

📄 host.pid — PID file for scorpiox-host daemon

📁 .scorpiox/

📄 scorpiox-env.txt — Project-level configuration override

📄 required_skills.txt — Project-level required skills list

📄 sessions/<id>/ — Per-session data (conversation, logs, events, traces)

📄 conversations/ — Legacy conversation storage

📄 logs/ — Fallback log directory

📄 traffics/ — Legacy traffic capture sessions

📁 ~/.claude/

📄 .credentials.json — Claude Code OAuth tokens

📄 scorpiox-env.txt — User-level config (cascade tier: user)

📄 commands/ — User slash commands (.md/.sh/.ps1)

📄 skills/ — User skill directories (SKILL.md)

📄 required_skills.txt — User-level required skills

📁 .claude/

📄 commands/ — Project slash commands (.md/.sh/.ps1)

📄 skills/ — Project skill directories (SKILL.md)

📄 required_skills.txt — Project-level required skills

📁 ~/.codex/

📄 auth.json — OpenAI Codex OAuth tokens

Configuration Files

`scorpiox-env.txt` .txt

Key-value configuration with cascade: defaults → exe_dir → ~/.claude/ → CWD/.scorpiox/ → OS env vars

Locationexe_dir/, ~/.claude/, CWD/.scorpiox/

SchemaKEY=VALUE per line, # comments, blank lines ignored

Read bysx, scorpiox-config, scorpiox-mcp, sx_config (libsxutil)

Written byscorpiox-config, sx_config_write_key()

PROVIDER=claude_code
MODEL=opus
STREAMING=0
TOOLS=1

`config-snapshot.txt` .txt

Frozen copy of all config key-value pairs at session start

Location.scorpiox/sessions/<id>/

SchemaKEY=VALUE per line

Read bydeveloper (post-mortem)

Written bysx_session (libsxutil)

PROVIDER=claude_code
MODEL=opus
MAX_TOKENS=16384

`scorpiox-init.txt` .txt

Installation/service configuration for scorpiox init system

Locationexe_dir/

SchemaKEY=VALUE per line

Read byscorpiox-init

Written byinstaller

SERVICE_NAME=scorpiox-server
PORT=8080

Session Files

`conversation.json` .json

Full conversation history — messages, tool uses, tool results

Location.scorpiox/sessions/<id>/

Schema{"id","created","cwd","messages":[{"role","content","tool_id","tool_name","tool_input","is_error"}]}

Read bysx, scorpiox-transcript, scorpiox-rewind

Written bysx_conversation (libsxutil)

{"id":"20260507-a1b2","created":"2026-05-07T19:05:26Z","messages":[]}

`meta.json` .json

Session metadata — model, provider, timing, usage summary

Location.scorpiox/sessions/<id>/

Schema{"session_id","model","provider","start_epoch","end_epoch","duration_s","total_turns","input_tokens","output_tokens"}

Read bysx, scorpiox-host, sxui_resume

Written bysx_session (libsxutil)

{"session_id":"20260507-a1b2","model":"opus","provider":"claude_code","total_turns":12}

`session.log` .log

sx_log output — timestamped DEBUG/INFO/WARN/ERROR with source location

Location.scorpiox/sessions/<id>/

Schema[HH:MM:SS.mmm] [LEVEL] [file:line] message

Read bydeveloper

Written bysx_log (libsxutil)

[19:05:26.123] [INFO] [sx.c:42] session started

`agent.log` .log

Agent-level logging — API requests, responses, tool uses, errors

Location.scorpiox/sessions/<id>/

Schema[HH:MM:SS] [TYPE] message

Read bydeveloper

Written bysx_session_agent_log()

[19:05:27] [REQUEST] POST /v1/messages
[19:05:28] [TOOL_USE] Bash: ls -la

`events.jsonl` .jsonl

Structured event log — machine-parseable JSON Lines for telemetry

Location.scorpiox/sessions/<id>/

Schema{"ts":"ISO8601","event":"event_name","data":{...}}

Read byscorpiox-host, scorpiox-sdk, external tooling

Written bysx_session_emit_event()

{"ts":"2026-05-07T19:05:26Z","event":"tool_use","data":{"tool":"Bash"}}

`trace.jsonl` .jsonl

Data flow trace — checkpoint pipeline debugging (API_RESPONSE → TOOL_USE → CONV_SAVE)

Location.scorpiox/sessions/<id>/

Schema{"ts":"HH:MM:SS.mmm","cp":"CHECKPOINT","key":"value"}

Read bydeveloper (debugging)

Written bysx_trace (libsxutil)

{"ts":"19:05:26.100","cp":"API_RESPONSE","tokens":1234}

Extensibility Files

`required_skills.txt` .txt

Skill names loaded into system prompt (cascade: user → project → .scorpiox → session)

Location~/.claude/, .claude/, .scorpiox/, .scorpiox/sessions/<id>/

SchemaOne skill name per line, # comments, blank lines ignored

Read bysx, sx_skills (libsxutil)

Written byuser (manual)

preferred-file-tools
googlemaps
create-command

`CLAUDE.md` .md

Project instructions appended to system prompt — conventions, rules, context

LocationProject root, parent dirs (up to 2 levels), ~/.claude/CLAUDE.md

SchemaMarkdown — free-form text, headings, code blocks, lists

Read bysx, sx_system_prompt (libsxutil)

Written byuser (manual)

# Project Instructions

## Rules
- Use tabs for indentation

`SKILL.md` .md

Skill definition — YAML frontmatter (name, description, has_args) + Markdown body

Location~/.claude/skills/<name>/, .claude/skills/<name>/

Schema---\nname: skill-name\ndescription: ...\n---\n\nMarkdown instructions

Read bysx, sx_skills (libsxutil)

Written byuser or agent

---
name: googlemaps
description: Google Maps API
---

Use scorpiox-googlemaps CLI...

`Slash command (.md)` .md

Custom slash command — Markdown content sent as user message

Location~/.claude/commands/, .claude/commands/

SchemaMarkdown with optional $ARGUMENTS placeholder

Read bysx, sx_slash (libsxutil)

Written byuser or agent

Review the following code for security issues:
$ARGUMENTS

`Slash command script` .sh / .ps1

Executable slash command — shell script, stdout piped to conversation

Location~/.claude/commands/, .claude/commands/

SchemaExecutable shell script, $ARGUMENTS as env var

Read bysx, sx_slash (libsxutil)

Written byuser or agent

#!/bin/bash
echo "Running tests..."
python -m pytest $ARGUMENTS

`MCP file (.mcp)` .mcp

MCP server definitions — compact format for stdio-based MCP servers

LocationProject root, ~/.claude/

SchemaJSON-like compact format with server name, command, args, env

Read bysx, sx_mcp (libsxutil)

Written byuser (manual)

`MCP servers JSON` .json

MCP server definitions — Claude-compatible JSON with mcpServers object

Location.claude/mcp_servers.json

Schema{"mcpServers":{"name":{"command":"...","args":[],"env":{}}}}

Read bysx, sx_mcp (libsxutil)

Written byuser (manual)

{"mcpServers":{"filesystem":{"command":"npx","args":["-y","@anthropic/mcp-fs"]}}}

Traffic Capture Files

`Traffic raw files` .txt / .bin / .json

Individual HTTP request/response headers and bodies from MITM proxy

Location.scorpiox/sessions/<id>/traffic/

Schemareq_NNNN.txt (headers), req_NNNN_body.bin/json, resp_NNNN.txt, resp_NNNN_body.bin/json

Read byscorpiox-traffic, developer

Written bysx_traffic (libsxnet)

`Traffic raw_messages` .json / .txt

Filtered subset — only /v1/messages API requests/responses

Location.scorpiox/sessions/<id>/traffic/raw_messages/

SchemaSame as traffic raw files, filtered to API calls only

Read byscorpiox-transcript, developer

Written bysx_traffic (libsxnet)

`summary.json` .json

Quick overview of all captured HTTP requests in a traffic session

Location.scorpiox/sessions/<id>/traffic/

Schema{"total_requests":N,"requests":[{"method":"GET","url":"...","status":200}]}

Read byscorpiox-traffic, developer

Written bysx_traffic (libsxnet)

`conversation.jsonl` .jsonl

Sequential request-response log — machine-parseable traffic conversation

Location.scorpiox/sessions/<id>/traffic/

SchemaJSON Lines — one request-response pair per line

Read byscorpiox-transcript, external tooling

Written bysx_traffic (libsxnet)

`all.har` .har

Standard HTTP Archive — importable into Chrome DevTools, HAR viewers

Location.scorpiox/sessions/<id>/traffic/

SchemaHAR 1.2 format — standard HTTP Archive specification

Read byChrome DevTools, HAR viewers, Fiddler

Written bysx_traffic (libsxnet)

`Curl replay scripts` .sh

Generated curl commands to replay captured HTTP requests

Location.scorpiox/sessions/<id>/traffic/

SchemaExecutable shell script with curl commands

Read bydeveloper (replay)

Written bysx_traffic (libsxnet)

SDK & Integration Files

`msg_NNNN_type.txt` .txt

Per-turn message files for SDK consumers (--emit-session / --headless)

Location.scorpiox/sessions/<id>/messages/

SchemaPlain text — one file per conversation turn, type in filename

Read byscorpiox-sdk, scorpiox-host, external tooling

Written bysx_session_emit()

`msg_NNNN_event.json` .json

Structured event emission per turn for SDK consumers

Location.scorpiox/sessions/<id>/messages/

Schema{"turn":N,"event":"...","data":{...}}

Read byscorpiox-sdk, scorpiox-host

Written bysx_session_emit_event()

`msg_NNNN_usage.json` .json

Token usage stats per turn for billing/monitoring

Location.scorpiox/sessions/<id>/messages/

Schema{"turn":N,"input_tokens":N,"output_tokens":N,"cache_read":N,"cache_write":N}

Read byscorpiox-sdk, billing tooling

Written bysx_session_emit_usage()

`Rewind audit files` .json / .log

Before/after snapshots and event log for conversation rewind

Location.scorpiox/sessions/<id>/rewinds/

Schemabefore.json, after.json (conversation snapshots), rewind.log (event log)

Read bydeveloper (audit trail)

Written byscorpiox-rewind

Container & Runtime Files

`Container image tarball` .tar

Rootfs tar archive for scorpiox-unshare container runtime

Location~/.scorpiox/images/

SchemaStandard tar archive — extracted to rootfs directory

Read byscorpiox-unshare

Written byscorpiox-unshare (pull/import)

`OCI image layout` (directory)

OCI-compliant container image with index.json, manifests, layer blobs

Location~/.scorpiox/images/<name>/

SchemaOCI Image Layout Spec — index.json, oci-layout, blobs/sha256/

Read byscorpiox-unshare

Written byscorpiox-unshare (pull)

`BIOS firmware binary` .bin

x86 BIOS ROM for scorpiox-vm KVM virtual machine boot

Locationexe_dir/bios.bin

SchemaRaw binary — x86 BIOS ROM image

Read byscorpiox-vm

Written bybuild system

`host.pid` .pid

PID file for scorpiox-host daemon process

Location~/.scorpiox/host.pid

SchemaSingle line — process ID integer

Read byscorpiox-host (startup check)

Written byscorpiox-host

`Claude Code credentials` .json

OAuth access/refresh tokens for Claude Code API

Location~/.claude/.credentials.json

Schema{"access_token":"...","refresh_token":"...","expires_at":N}

Read byscorpiox-claudecode-fetchtoken, sx

Written byscorpiox-claudecode-fetchtoken

`Codex auth.json` .json

OpenAI Codex OAuth tokens

Location~/.codex/auth.json

Schema{"token":"...","refresh":"..."}

Read byscorpiox-codex-fetchtoken, sx

Written byscorpiox-codex-fetchtoken

File Formats

Contents

Overview

Directory Structure

Configuration Files

scorpiox-env.txt .txt

config-snapshot.txt .txt

scorpiox-init.txt .txt

Session Files

conversation.json .json

meta.json .json

session.log .log

agent.log .log

events.jsonl .jsonl

trace.jsonl .jsonl

Extensibility Files

required_skills.txt .txt

CLAUDE.md .md

SKILL.md .md

Slash command (.md) .md

Slash command script .sh / .ps1

MCP file (.mcp) .mcp

MCP servers JSON .json

Traffic Capture Files

Traffic raw files .txt / .bin / .json

Traffic raw_messages .json / .txt

summary.json .json

conversation.jsonl .jsonl

all.har .har

Curl replay scripts .sh

SDK & Integration Files

msg_NNNN_type.txt .txt

msg_NNNN_event.json .json

msg_NNNN_usage.json .json

Rewind audit files .json / .log

Container & Runtime Files

Container image tarball .tar

OCI image layout (directory)

BIOS firmware binary .bin

host.pid .pid

Claude Code credentials .json

Codex auth.json .json

`scorpiox-env.txt` .txt

`config-snapshot.txt` .txt

`scorpiox-init.txt` .txt

`conversation.json` .json

`meta.json` .json

`session.log` .log

`agent.log` .log

`events.jsonl` .jsonl

`trace.jsonl` .jsonl

`required_skills.txt` .txt

`CLAUDE.md` .md

`SKILL.md` .md

`Slash command (.md)` .md

`Slash command script` .sh / .ps1

`MCP file (.mcp)` .mcp

`MCP servers JSON` .json

`Traffic raw files` .txt / .bin / .json

`Traffic raw_messages` .json / .txt

`summary.json` .json

`conversation.jsonl` .jsonl

`all.har` .har

`Curl replay scripts` .sh

`msg_NNNN_type.txt` .txt

`msg_NNNN_event.json` .json

`msg_NNNN_usage.json` .json

`Rewind audit files` .json / .log

`Container image tarball` .tar

`OCI image layout` (directory)

`BIOS firmware binary` .bin

`host.pid` .pid

`Claude Code credentials` .json

`Codex auth.json` .json