.claude.json — Complete Field Reference

The file ~/.claude.json (or ~/.claude-<oauth-suffix>.json) is the central configuration file of Claude Code (internal codename: Tengu). It is read on every startup and written whenever state changes.

Important: Most fields are internal state, not user configuration. Settings like model, permissions and hooks belong in ~/.claude/settings.json.

This gist documents every single field — derived from the source type GlobalConfig in src/utils/config.ts.

File Structure

The file has two levels:

1. Global fields (top-level) — apply to all projects
2. Project fields (under projects[path]) — stored per git root

Key Sections

Installation & Updates

{
  "numStartups": 342,
  "installMethod": "native",
  "autoUpdates": true,
  "firstStartTime": "2025-06-15T10:30:00Z",
  "migrationVersion": 12
}

numStartups is incremented on every start and serves as an internal counter for tip display, onboarding logic and feature rollouts.

User & Authentication

{
  "userID": "user_abc123",
  "oauthAccount": {
    "accountUuid": "...",
    "emailAddress": "...",
    "organizationUuid": "...",
    "billingType": "pro"
  },
  "primaryApiKey": "sk-ant-..."
}

The userID is also the basis for the deterministic companion calculation (see Buddy Patch post).

UI, Theme & Editor

This is where user preferences set via the CLI live:

| Field | Description | |-------|-------------| | theme | 'dark', 'light', 'light-daltonized', ... | | editorMode | 'vim', 'emacs', etc. | | verbose | Verbose output | | diffTool | 'terminal' or 'auto' (VSCode) | | autoCompactEnabled | Auto-compact on long context |

Terminal & IDE Integration

Claude Code remembers the state of various terminal integrations:

• iTerm2: Key bindings, backup path, setup status
• Terminal.app: Option-as-Meta, backup path
• IDE Auto-Connect: Automatic VSCode/JetBrains connection
• Deep Links: claude-cli:// URL handling

Companion / Buddy

{
  "companion": {
    "species": "dragon",
    "rarity": "epic",
    "stats": { "debugging": 8, "patience": 5, "chaos": 7, "wisdom": 9, "snark": 6 }
  },
  "companionMuted": false
}

The companion field is generated on first startup from hash(userId + salt). Deleting it triggers a recalculation on the next start.

MCP Servers

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "env": { "API_KEY": "..." }
    }
  }
}

Global MCP servers (user scope). Project-specific servers belong in .mcp.json in the project root.

Subscription & Billing

A whole block of cache fields for subscription status, upsell counters and feature access. Interesting: you can see which subscription tiers exist and how Claude Code caches access:

• hasAvailableSubscription — Does the user have an active subscription?
• s1mAccessCache — Sonnet-1M access per organisation
• passesEligibilityCache — Guest pass eligibility
• overageCreditGrantCache — Extra usage credits

Project Fields

Under projects["/path/to/repo"], Claude Code stores per-project state:

Tools & Permissions

{
  "projects": {
    "/Users/me/my-project": {
      "hasTrustDialogAccepted": true,
      "allowedTools": ["Read", "Write", "Bash", "Glob", "Grep"]
    }
  }
}

Session Metrics

After each session, metrics are saved — useful for tracking your own usage:

| Field | Description | |-------|-------------| | lastCost | Cost of the last session | | lastDuration | Duration of the last session | | lastTotalInputTokens | Input tokens | | lastTotalOutputTokens | Output tokens | | lastLinesAdded | Lines added | | lastLinesRemoved | Lines removed |

Worktree Sessions

{
  "activeWorktreeSession": {
    "originalCwd": "/Users/me/project",
    "worktreePath": "/Users/me/project/.worktrees/feature-x",
    "worktreeName": "feature-x",
    "sessionId": "sess_123"
  }
}

Feature Flags (tengu_*)

Claude Code uses GrowthBook for feature flags. The flags are cached in cachedGrowthBookFeatures and loaded on startup.

Flag values are resolved in this order:

1. CLAUDE_INTERNAL_FC_OVERRIDES env variable (Anthropic-internal only)
2. growthBookOverrides in ~/.claude.json (internal only, via /config)
3. In-memory GrowthBook cache (latest network fetch)
4. cachedGrowthBookFeatures on disk (offline fallback)

The gist contains a complete table of all 100+ tengu_ flags with descriptions, default values and build flag status — from agent swarms to voice mode to computer use.

Conclusion

~/.claude.json is far more than a simple config file — it is the complete persistent state of Claude Code. Understanding what is stored here helps you debug Claude Code better, narrow down issues faster, and track your own usage more effectively.

The full reference with all fields, types and descriptions is available in the Gist on GitHub.