Using Claude Code CLI Subscription in SCORPIOX CODE

You have a Claude Code CLI subscription (a Claude Pro or Max plan, or a Claude Code seat) and you don't want to meter per-token against an Anthropic API key. You can use it directly in SCORPIOX CODE. Instead of billing API tokens, the Claude Code provider signs you in with the same OAuth session login the Claude Code CLI performs and sends every request to the Anthropic endpoint your subscription already pays for — wearing the same wire identity the CLI itself wears.

This page walks through the session login, where the token is stored and how it is refreshed automatically, the configuration keys behind PROVIDER=claude_code, multi-account setups with profiles (/profile and /use), how to drive a login without a TTY (machine mode), and how a direct subscription differs from standard API-key usage in the Anthropic provider.

Docs for SCORPIOX CODE @ 77c49df.

When to use this provider

If you are instead calling the Anthropic API with an API key (ANTHROPIC_API_KEY), that is the Anthropic provider (PROVIDER=anthropic) — a different billing model for the same models. See Claude Code provider vs. the Anthropic API-key provider below.

Step 1 — Sign in with the OAuth session flow

The login is the OAuth authorization-code flow with PKCE (Proof Key for Code Exchange) — the same flow the official Claude Code CLI performs, using the Claude Code client identity. SCORPIOX CODE generates the PKCE verifier and challenge for you, prints one authorization URL, and waits for you to paste the resulting authorization code back. It is deliberately SSH- and headless-friendly: no browser is required on the machine you run from.

scorpiox-claudecode-login

You will see something like this:

scorpiox-claudecode-login v...

Generating PKCE challenge...

Open this URL in your browser to authorize:

  https://claude.com/cai/oauth/authorize?code=true&response_type=code&...&code_challenge=...&code_challenge_method=S256

After logging in, paste the authorization code below.
Code: >

Do exactly what it says:

1. Open the printed URL in a browser — on any device, wherever you are signed into Claude.
2. Log in to your Claude account and approve the requested permissions.
3. The browser lands on a Claude callback page. Copy the code shown there and paste it back into the terminal.

SCORPIOX CODE exchanges the code for an access token and a refresh token (the PKCE verifier proves the exchange came from the same terminal that started the flow) and saves both. On success you will see:

Login successful
  Saved to /home/you/.claude/.credentials.json
  Token expires in 86400s

A few things worth knowing about this flow:

• Paste the code or the whole redirect fragment. If you paste the full callback address, the #state fragment is stripped for you and only the code is used.
• Never share the authorization code. It is a credential: single-use, short-lived, and anyone holding it while you are mid-login can bind it to their own request.
• No browser on the box? No problem. Approve from your laptop, phone, or a kiosk and paste the code back into the SSH session.
• The access token is short-lived by design — about a day. You never manage that; see Token persistence and automatic refresh.

Overwriting existing credentials

If a credential file already exists, the login refuses to clobber it:

Credentials already exist: /home/you/.claude/.credentials.json
Use --force to overwrite.

Pass --force to re-authorize deliberately and replace the stored token — for example after an account change, a plan change, or a refresh that keeps failing:

scorpiox-claudecode-login --force

Named accounts

By default the login writes ~/.claude/.credentials.json. To keep several accounts side by side, give each one a name:

scorpiox-claudecode-login --name personal   # -> ~/.claude/accounts/personal.json
scorpiox-claudecode-login --name work       # -> ~/.claude/accounts/work.json

Account names accept letters, digits, -, _ and . (up to 64 characters). A named file is only used by the provider when a profile points CLAUDE_CODE_CREDENTIALS_FILE at it — see Multi-account: profiles and switching.

Creating the claude_code profile

At the end of a successful login, SCORPIOX CODE offers to write a ready-made profile (the prompt is skipped when stdin is not a TTY):

Create 'claude_code' config profile?
  Will create: /home/you/.claude/scorpiox-env/claude_code.txt
  Contents:
    PROVIDER=claude_code
    CLAUDE_CODE_TOKEN_SOURCE=local
    MODEL=claude-opus-4-6

Create? [Y/n]

Say yes and the profile is written to ~/.claude/scorpiox-env/claude_code.txt, ready to activate with /profile claude_code. Decline and the tool prints the exact commands to create the file by hand instead.

Step 2 — Turn on the Claude Code provider

The provider switches on with PROVIDER=claude_code. For a personal subscription you also set CLAUDE_CODE_TOKEN_SOURCE=local, so the provider reads the credential file your login just wrote. That is the whole setup:

PROVIDER=claude_code
CLAUDE_CODE_TOKEN_SOURCE=local

Activate the profile — or put those keys in any cascade tier of scorpiox-env.txt, or export them as OS environment variables — and SCORPIOX CODE connects:

/profile claude_code      # activate this profile and persist it

You can also select the provider for a single run from the command line:

sx --provider claude_code -p 'explain this code'
sx --provider claude_code -m opus -p 'review this'

Configuration keys

All keys can live in any cascade tier of scorpiox-env.txt, in a named profile, or as OS environment variables — the highest tier that sets a key wins. See Configuration and Profiles for the full cascade and precedence rules.

In the config editor (/config in a session, or scorpiox-config from a shell) the CLAUDE_CODE_* keys live in the Provider & Authentication section and appear once PROVIDER is claude_code. The remote-token keys are shown conditionally: CLAUDE_CODE_REMOTE_URL and TOKEN_HTTP_API_KEY when the source is http, the CLAUDE_CODE_SSH_* set when the source is ssh. CLAUDE_CODE_CREDENTIALS_FILE is honored everywhere but is not part of that editor's list — set it in a profile file or the environment.

Where the token lives

On login, SCORPIOX CODE writes the OAuth tokens to ~/.claude/.credentials.json under a claudeAiOauth section:

~/.claude/.credentials.json
  claudeAiOauth:
    accessToken    <- short-lived bearer token sent with every request
    refreshToken   <- what makes renewal possible without signing in again
    expiresAt      <- expiry timestamp in milliseconds
    scopes         <- the permissions the login was granted

No API key is involved, and no API key is ever written. With CLAUDE_CODE_TOKEN_SOURCE=local, every request reads the current access token from that file, so a refresh that happens outside the session is picked up on the next turn.

Treat that file as what it is: a live credential that can renew your account session. Do not commit it, do not copy it into shared dotfile repos, and do not loosen its permissions.

Token persistence and automatic refresh

The access token from the OAuth session is short-lived by design — but you do not manage it. SCORPIOX CODE handles the whole lifecycle:

• Proactive refresh. Before each request the provider compares the stored expiresAt with the clock. Inside a 5-minute buffer of expiry it runs the refresh step — a renewal against Anthropic's OAuth endpoint using the stored refresh token — writes the new pair back to the credential file (keeping a .backup copy alongside it), and re-reads the file. In-flight work never hits an expired credential.
• Reactive recovery. If a request still comes back 401 Unauthorized or 403 Forbidden, the provider refreshes the token once and retries the request immediately. A second failure after a refresh is reported as a permanent authentication error — at that point the token (or the account behind it) genuinely needs a re-login.
• Remote sources always fetch fresh. In http, ssh, or tcp modes the token is re-fetched on every request: the remote endpoint is the source of truth and may have rotated or revoked an old token at any time, so there is no local expiry to reason about.
• Two tries, then give up. A refresh that fails is retried once after a short pause before the turn is failed, so a blip on the token endpoint does not abort a long run.

Manual refresh

You can force the same renewal from a shell at any time:

scorpiox-claudecode-refreshtoken                       # refresh only if expired
scorpiox-claudecode-refreshtoken --force               # always refresh
scorpiox-claudecode-refreshtoken --credentials-file ~/.claude/accounts/work.json

The tool prints the current and new expiry times, backs up the credential file before touching it, and rewrites only the three OAuth fields — everything else in the file is preserved byte for byte. --verbose additionally prints the old and new token material to the terminal, which is occasionally useful for diagnostics and exactly as sensitive as it sounds; run it on a machine you trust.

As long as the refresh token in the credential file is intact, you generally sign in once. If you ever see an unauthorized or token-expired hint, the fix is almost always one of:

scorpiox-claudecode-refreshtoken --force   # token expired — renew it
scorpiox-claudecode-login --force          # refresh failed / account changed — re-login

Inspecting the resolved token

For diagnostics you can resolve the token exactly the way the provider does, without making a model request:

scorpiox-claudecode-fetchtoken -config --verbose

The tool prints one JSON line containing the access token and its expiry, and --verbose adds the cascade tiers it consulted to get there. It reads the same keys as the provider — CLAUDE_CODE_TOKEN_SOURCE and friends — so what it resolves is what a request would send. Note that, like --verbose above, it prints live credential material: use it for checks, not for logging.

Checking your subscription usage

The provider runs against the same usage windows the Claude Code CLI enforces. Check how full they are with:

scorpiox-claudecode-usage            # human-readable summary
scorpiox-claudecode-usage --json     # raw JSON

You get one row per active window — the 5-hour session window, the weekly window, weekly per-model windows (Opus, Sonnet, OAuth apps), and any others your plan exposes — each with its utilization percentage, the reset time in UTC and your local timezone, and a countdown to the reset. When your plan has an extra-usage allowance, its enabled state, utilization, and used-versus-limit spend are shown too. That is exactly what you want to know before kicking off a long autonomous run: whether the window will hold and when it turns over.

Inside a session, /usage runs the same tool and shows the result as Claude Usage when the Claude Code provider is active. In addition, the per-response 5h: and 7d: figures in the status bar come straight from the rate-limit headers Anthropic returns on this provider, so the live utilization is visible while you work — see Token Usage Observability.

Choosing a model

MODEL accepts either a short alias or a full Claude model ID. The aliases at this commit resolve to:

Anything that is not one of the three aliases — a newer claude-* ID your account has access to, for example — is sent to the endpoint unchanged. That is how you run a model version the built-in defaults do not know about without editing anything.

Model overrides

Pin a specific version to each alias with the override keys:

• CLAUDE_MODEL_OPUS_ID_OVERRIDE
• CLAUDE_MODEL_SONNET_ID_OVERRIDE
• CLAUDE_MODEL_HAIKU_ID_OVERRIDE

When set, an override replaces the built-in ID for that alias — so MODEL=opus resolves to your pinned version instead of the default one. Full model IDs written directly in MODEL are never overridden; they pass through as-is. Leave an override empty to keep the built-in default.

Switch models at runtime without editing any file with the in-session /model command, or set a standing default in your profile. /model takes the same values as MODEL — aliases and full IDs both work. You can also pin a model for a single run with sx -m opus, or override any key for that run only with sx -e CLAUDE_CODE_TOKEN_SOURCE=local.

You can list everything the endpoint currently advertises with:

scorpiox-claudecode-models              # full model list, raw JSON
scorpiox-claudecode-models <model-id>   # one model's detail

What a request looks like

For each turn SCORPIOX CODE sends one Messages API request that is wire-compatible with the Claude Code CLI:

1. Endpoint — https://api.anthropic.com/v1/messages?beta=true (or your proxy host, same path). Requests carry the Claude Code beta flags, including the OAuth beta and interleaved thinking.
2. Identity — the access token as an OAuth bearer token, plus the CLI's own client headers: a claude-cli/<version> (external, cli) user-agent built from CLAUDE_CODE_CLI_VERSION, and the standard client metadata headers the CLI sends. This is what makes the request indistinguishable from the CLI you already use.
3. System prompt — sent as two text blocks, each marked as ephemeral cache control so the provider can reuse the prefix between turns.
4. Messages — the conversation, with consecutive same-role entries grouped, and a cache breakpoint on the last block of each role. A resumed-after-compaction conversation gets a synthetic user marker so the history stays valid.
5. Thinking and tools — an extended-thinking block with THINKING_BUDGET tokens when THINKING=1, and the tool definitions when TOOLS=1.

Each request gets a five-minute timeout, so long agentic turns are not cut off mid-flight. The response comes back as content blocks with a stop reason and a usage object; token counts, cache read/write figures, and the rate-limit utilization are surfaced in the status bar and the session stats — see Token Usage Observability.

Streaming and speed estimates

STREAMING=0 (the default) sends one request and parses one complete response. STREAMING=1 asks for server-sent events instead; the response is parsed the same way either way, so the only practical difference is how the body is delivered. Pair streaming with the opt-in speed estimate to get live prompt and generation rates in the status bar:

STREAMING=1
USAGE_SPEED_ESTIMATE=1

Estimates include network latency and wear a tilde (~pp / ~tg) in the status bar to say so.

Proxy and endpoint overrides

Two keys decide where requests actually go, and they interact:

• CLAUDE_CODE_API_URL replaces the Anthropic host. It is a domain only — api.anthropic.com by default — and the /v1/messages?beta=true path is appended for you. Use it when a private DNS name or an internal mirror fronts the same Anthropic surface.
• CLAUDE_CODE_PROXY_URL with CLAUDE_CODE_PROXY_ENABLED=1 routes requests through a transparent reverse proxy instead. The request still declares the real Anthropic host in its host header regardless of the proxy domain, so the upstream sees a normal Claude Code request.

Failover behavior is what CLAUDE_CODE_PROXY_STRICT is for:

A typical setup for a network where Anthropic is reachable only through the proxy:

PROVIDER=claude_code
CLAUDE_CODE_TOKEN_SOURCE=local
CLAUDE_CODE_PROXY_ENABLED=1
CLAUDE_CODE_PROXY_URL=anthropic.scorpiox.net
CLAUDE_CODE_PROXY_STRICT=1

Remote token sources: http, ssh, tcp

local is all a personal subscription needs. The other three sources exist so that one credential can serve a whole fleet — a build box, a container, or a machine that should never hold the credential file itself:

The token server speaks a small request/response protocol (SXV1 ... TYPE=claude) and answers with the same credential JSON the local file holds, so the provider consumes all four sources identically. In http, ssh, and tcp modes the token is re-fetched on every request and no refresh is performed locally — the endpoint owning the credential is responsible for keeping it valid.

Multi-account: profiles and switching

Many people have more than one Claude account (personal plus work, for example). The Claude Code provider supports that in two layers: named credential files and named config profiles.

Save more than one login

scorpiox-claudecode-login --name personal   # -> ~/.claude/accounts/personal.json
scorpiox-claudecode-login --name work       # -> ~/.claude/accounts/work.json

Bind each login to a profile

Now make one profile per account and point CLAUDE_CODE_CREDENTIALS_FILE at the right file, so the profile always uses that account:

# ~/.claude/scorpiox-env/claude-personal.txt
PROVIDER=claude_code
CLAUDE_CODE_TOKEN_SOURCE=local
CLAUDE_CODE_CREDENTIALS_FILE=~/.claude/accounts/personal.json
MODEL=claude-opus-4-6

# ~/.claude/scorpiox-env/claude-work.txt
PROVIDER=claude_code
CLAUDE_CODE_TOKEN_SOURCE=local
CLAUDE_CODE_CREDENTIALS_FILE=~/.claude/accounts/work.json
MODEL=claude-sonnet-4-6

Profiles can live at any tier — ~/.claude/scorpiox-env/<name>.txt for your own machine, .scorpiox/scorpiox-env/<name>.txt committed to a project so the whole team gets the same account and model.

Switch accounts and models in-session

With those profiles in place, switching accounts is just switching profiles — no re-login, no restart:

/profile claude-work      # persistent — writes ACTIVE_PROFILE, survives restarts
/use    claude-personal   # session-only — gone when the session ends
/profile                  # list profiles and the active one (opens the picker where available)
/profile off              # deactivate and drop back to the base cascade

/profile and /use both trigger a live provider reload, so the new account and model take effect immediately. If the switch cannot complete, SCORPIOX CODE reverts to the previous profile — you are never left half-switched. The difference is scope: /profile <name> persists (it writes ACTIVE_PROFILE, so it survives restarts), while /use <name> is session-only (an in-memory switch that disappears when the session ends). See Configuration and Profiles for the full switching semantics.

Inspect what is actually configured

Use scorpiox-config to see resolved values and where each one comes from (which cascade tier won):

scorpiox-config            # open the interactive config editor
scorpiox-config --verbose  # print key values with their source tier

--verbose reports CLAUDE_CODE_TOKEN_SOURCE, CLAUDE_CODE_API_URL, the proxy keys, MODEL, and ACTIVE_PROFILE, so you can confirm you are pointed at the account and endpoint you expect before a long run.

Machine mode (no TTY)

Sometimes you cannot hold a terminal open between "here is the URL" and "paste the code" — a background agent, a CI step, or SCORPIO BOT's provider flow. The login ships an additive machine mode: the same PKCE flow split into separate, non-interactive commands that print a single line of JSON to stdout. Tokens are never printed — only status. Running the tool with no machine flag is the original interactive behaviour, unchanged.

A typical machine-mode login:

# 1. Start — prints the URL to open
scorpiox-claudecode-login --start
# {"ok":true,"provider":"claudecode","flow":"paste_code","auth_url":"https://claude.com/cai/oauth/authorize?...","expires_in":600,"hint":"Sign in, then paste the code shown on the callback page."}

# 2. Open that URL in any browser, sign in, approve, copy the code.

# 3. Finish — exchange the code
scorpiox-claudecode-login --finish "$CODE" --create-profile
# {"ok":true,"provider":"claudecode","logged_in":true,"path":"/home/you/.claude/.credentials.json","expires_in":86400,"profile":"claude_code","profile_created":true}

Things worth knowing:

• State survives between commands. Between --start and --finish the PKCE verifier and state live in ~/.claude/.login-pending/ (mode 0600), so the two calls can be separate processes on the same node.
• Ten-minute window. If --finish comes more than 10 minutes after --start, the pending state is dropped and the command fails with expired — run --start again for a fresh challenge.
• One JSON line per call. Everything is on stdout as a single line; the caller reads the last line that starts with {. A failure looks like {"ok":false,"provider":"claudecode","error":"...","detail":"..."} — for example exists (credentials already there, pass --force), exchange (the code was wrong, already used, or expired), or no_pending (--finish without a --start).
• --status tells you where you stand. It reports logged_in, whether a refresh token is stored (has_refresh), whether the stored token is already past its expiresAt (expired), whether a login is mid-flight (pending), and whether the claude_code profile exists. Use it to decide whether a machine needs a login at all.
• Credential files written this way are mode 0600. Only the owning account can read them.

Claude Code provider vs. the Anthropic API-key provider

It is easy to confuse the two because they both run Anthropic models. Here is the difference:

Rule of thumb: a Claude / Claude Code seat, use claude_code. An API key or a custom endpoint, use anthropic.

Both providers reach Anthropic's Messages API and share the same request builder, but the credentials, headers, and billing are different. Only the Anthropic provider can be pointed at a non-Anthropic URL.

Gotchas

• The login command and the provider are separate. scorpiox-claudecode-login writes the token file and offers a profile. SCORPIOX CODE only uses it once PROVIDER=claude_code is active — via /profile, /use, ACTIVE_PROFILE, or the base cascade.
• The shipped configuration may point at the token server, not your login. A stock scorpiox-env.txt can ship with CLAUDE_CODE_TOKEN_SOURCE=tcp. For a personal subscription, set it to local in your profile — otherwise every request fetches the token from the fleet's token server instead of the credential file you just wrote.
• Named accounts live in ~/.claude/accounts/, not the default file. --name work writes ~/.claude/accounts/work.json, and a profile only uses it if CLAUDE_CODE_CREDENTIALS_FILE points there. Leaving the override empty always means the default file.
• CLAUDE_CODE_CREDENTIALS_FILE is honored but not listed in the config editor. It is read from the cascade like any key, so put it in a profile file or export it — do not look for it in the interactive editor's key list.
• /profile persists; /use does not. Use /profile to make a Claude Code account your standing default and /use to hop to it for a single session without writing anything.
• Environment variables beat every file. A CLAUDE_CODE_TOKEN_SOURCE exported in a shell outranks your profile. When a setting "won't stick", check the environment before blaming the files.
• Refreshing is automatic, but re-login is the fallback. If scorpiox-claudecode-refreshtoken --force keeps failing — expired refresh token, account changed, plan changed — do a full scorpiox-claudecode-login --force to re-bind.
• Subscription windows are enforced upstream. The 5-hour and weekly limits are Anthropic's, not SCORPIOX CODE's. Watch them with scorpiox-claudecode-usage instead of guessing.
• Non-strict proxy mode degrades silently. With CLAUDE_CODE_PROXY_STRICT=0 a proxy outage quietly switches that request to the direct endpoint. If your network only allows egress through the proxy, set strict mode so failures are loud.
• Diagnostics can print live token material. scorpiox-claudecode-fetchtoken -config and scorpiox-claudecode-refreshtoken --verbose both emit credential values to the terminal. Fine for a check on your own box; avoid them in shared logs and CI output.
• The browser build is different. In the WASM/browser target there is no local credential file and no profile switching: the token comes from CLAUDE_CODE_REMOTE_URL, and streaming is always off for this provider.
• Profile switches are live and safe. /profile and /use swap the provider in place and revert automatically if the new profile cannot initialize.

Quick reference

Sign in once, let the refresh loop keep the token alive, and pick the profile that points at the account and model you want.

See also

• Configuration and Profiles — the cascade every key above is read through, and /profile vs /use.
• Direct Anthropic API & Custom Endpoints — the key-based path to the same models, and when to prefer it.
• Using Google Antigravity CLI Subscription in SCORPIOX CODE — the Google-side subscription login, including Claude models via Google.
• Token Usage Observability — where the token counts and the 5h: / 7d: subscription windows show up.
• API Traffic Logging and Complete Remote Call Transparency — the verbatim on-disk record of every request, with the bearer token masked.