Configuration Reference

Receiver environment variables

All receiver configuration is via environment variables. Unrecognised variables are ignored. On startup the receiver prints all resolved values.

Plugin binary environment variables

These are set automatically by Claude Code from the plugin's userConfig and do not need to be configured manually.

Binary fallback: config.json

If the CLAUDE_PLUGIN_OPTION_* env vars are empty (e.g. when the plugin settings UI is unavailable), the binary reads:

<data_dir>/ccflux/config.json

Format:

{
  "endpoint": "https://ccflux.example.org/report",
  "token": "rtok_abc123..."
}

Set this file to mode 0600. If both the env vars and the config file are absent, the binary exits silently — no reporting occurs.

Development-only variables

Plugin userConfig fields

Configured via Claude Code plugin settings UI or CLAUDE_PLUGIN_OPTION_* env vars.

State files

The binary stores state in <data_dir>/ccflux/. For the default CC installation this is ~/.claude/ccflux/.

SQLite schema

CREATE TABLE refresh_tokens (
    token       TEXT PRIMARY KEY,
    email       TEXT NOT NULL,
    division      TEXT,
    expires_at  TIMESTAMP NOT NULL,
    revoked     INTEGER DEFAULT 0,
    created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE access_tokens (
    token           TEXT PRIMARY KEY,
    refresh_token   TEXT NOT NULL REFERENCES refresh_tokens(token),
    email           TEXT NOT NULL,
    expires_at      TIMESTAMP NOT NULL,
    created_at      TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE device_keys (
    public_key      TEXT PRIMARY KEY,
    email           TEXT NOT NULL,
    device_id       TEXT,
    registered_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    last_seen_at    TIMESTAMP,
    revoked         INTEGER DEFAULT 0
);

CREATE TABLE usage_events (
    id                  INTEGER PRIMARY KEY AUTOINCREMENT,
    received_at         TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    user_email          TEXT NOT NULL,
    user_token          TEXT NOT NULL,
    session_id          TEXT NOT NULL,
    turn_index          INTEGER NOT NULL,
    timestamp_utc       TIMESTAMP NOT NULL,
    session_start_utc   TIMESTAMP,
    model               TEXT NOT NULL,
    input_tokens        INTEGER NOT NULL DEFAULT 0,
    output_tokens       INTEGER NOT NULL DEFAULT 0,
    cache_read_tokens   INTEGER NOT NULL DEFAULT 0,
    cache_write_tokens  INTEGER NOT NULL DEFAULT 0,
    plugin_version      TEXT,
    schema_version      INTEGER NOT NULL DEFAULT 1,
    UNIQUE(session_id, turn_index, model)
);

The UNIQUE(session_id, turn_index, model) constraint handles idempotent retries: duplicate POSTs use INSERT OR IGNORE.

Receiver endpoints

Usage payload schema

The binary POSTs this JSON structure to /report:

{
  "schema_version": 1,
  "session_id": "uuid",
  "user_email": "jsmith@example.org",
  "turn_index": 42,
  "timestamp_utc": "2026-05-11T04:32:10Z",
  "session_start_utc": "2026-05-10T09:15:00Z",
  "models": {
    "claude-sonnet-4-6": {
      "input_tokens": 14200,
      "output_tokens": 1800,
      "cache_read_tokens": 9400,
      "cache_write_tokens": 0
    }
  },
  "plugin_version": "0.1.0"
}

A single turn may contain usage from multiple models (e.g. Sonnet for the main response plus a tool-use round with a different model). Each model gets its own key in models.

Prometheus metrics

Available at GET /metrics. All counters reset on receiver restart (in-memory).

403 error codes

When /report returns 403, the X-CCFLUX-Error response header contains a machine-readable code. The binary reads this and responds accordingly.