Claude Code credential & settings files

This document describes the on-disk files Claude Code manages for a user and which fields scitex-agent-container is allowed to read and surface.

Files

~/.claude.json

The main per-user settings JSON managed by Claude Code itself. Top-level keys relevant to agent orchestration:

  • oauthAccount (subdict): accountUuid, emailAddress, organizationUuid, organizationName, billingType, accountCreatedAt, subscriptionCreatedAt, hasExtraUsageEnabled, displayName, organizationRole.

  • hasAvailableSubscription (bool)

  • cachedExtraUsageDisabledReason (str, e.g. "out_of_credits")

  • overageCreditGrantCache (obj)

  • numStartups (int)

  • installMethod (str)

  • claudeCodeFirstTokenDate (str)

  • firstStartTime (str)

  • hasCompletedOnboarding (bool)

  • passesEligibilityCache (obj)

  • changelogLastFetched (str)

  • lastReleaseNotesSeen (str)

  • skillUsage (obj)

Any other keys (model caches, feature flags, editor state, MCP server definitions, per-project history) are considered opaque and MUST NOT be surfaced by our tooling.

~/.claude/.credentials.json

OAuth tokens for Claude.ai. Contains (inside a claudeAiOauth subdict): accessToken, refreshToken, expiresAt, scopes, subscriptionType, rateLimitTier.

RULE: this file MUST NEVER be read or emitted by scitex-agent-container tooling except for the non-secret strings subscriptionType and rateLimitTier. The extractor must not load, log, cache, or transmit any other field from this file. Tokens are the highest-sensitivity material on the host.

~/.claude/settings.json

Per-user Claude Code settings. Common keys: permissions, statusLine (command used to render the bottom bar, often claude-hud), enabledPlugins. Contains no secrets but may reveal which plugins / skills are enabled.

Fleet hosts

Each fleet host runs exactly one Claude Code OAuth identity shared by all tmux-managed agents on that host:

Host

Domain role

Credential home

MBA

scitex-orochi.com hub

~/.claude/

NAS

scitex.ai

~/.claude/

spartan

GPU worker

~/.claude/

ywata-note-win

Windows/WSL

~/.claude/

All tmux panes on a host inherit the same ~/.claude.json + ~/.credentials.json, so any head-agent view of “Claude account” is per-host, not per-agent.

What NOT to emit

The extraction layer MUST strip any field whose key or stringified value contains any of these substrings (case-insensitive):

  • accessToken

  • refreshToken

  • sk-ant-

  • Bearer (with trailing space)

  • secret

  • apiKey

  • claudeAiOauth

A post-extraction guard asserts the returned dict contains none of the above in either keys or values, and raises if violated.

Safe metadata fields (whitelist)

read_credentials_metadata() returns a flat dict with exactly these keys. Fields unavailable on disk are returned as None.

From ~/.claude.json oauthAccount:

  • account_uuid

  • email_address

  • organization_uuid

  • organization_name

  • billing_type

  • account_created_at

  • subscription_created_at

  • has_extra_usage_enabled

  • display_name

  • organization_role

From ~/.claude.json top level:

  • has_available_subscription

  • cached_extra_usage_disabled_reason

  • num_startups

  • install_method

  • claude_code_first_token_date

  • first_start_time

  • has_completed_onboarding

From ~/.claude/.credentials.json claudeAiOauth (only these two):

  • subscription_type

  • rate_limit_tier

From ~/.claude/settings.json:

  • status_line_command

  • enabled_plugins

Any addition to this list requires updating both this doc and the whitelist in src/scitex_agent_container/credentials.py.