ContextQMD
Back to Codexbar

Claude provider

docs/claude.md

0.246.6 KB
Original Source

Claude provider

Claude supports three usage data paths plus local cost usage. The main provider pipeline uses runtime-specific automatic selection, but the codebase still has multiple active Claude .auto decision sites while the refactor is pending. For the exact current-state parity contract, see docs/refactor/claude-current-baseline.md.

Data sources + selection order

Default selection (debug menu disabled)

  • App runtime main pipeline: OAuth API → CLI PTY → Web API.
  • CLI runtime main pipeline: Web API → CLI PTY.
  • Explicit picker modes (OAuth/Web/CLI) bypass automatic fallback.
  • A lower-level direct Claude fetcher still contains a separate .auto order. That inconsistency is tracked in docs/refactor/claude-current-baseline.md.

Usage source picker:

  • Preferences → Providers → Claude → Usage source (Auto/OAuth/Web/CLI).

Keychain prompt policy (Claude OAuth)

  • Preferences → Providers → Claude → Keychain prompt policy.
  • Options:
    • Never prompt: never attempts interactive Claude OAuth Keychain prompts.
    • Only on user action (default): interactive prompts are reserved for user-initiated repair flows.
    • Always allow prompts: allows interactive prompts in both user and background flows.
  • This setting only affects Claude OAuth Keychain prompting behavior; it does not switch your Claude usage source.
  • If Preferences → Advanced → Disable Keychain access is enabled, this policy remains visible but inactive until Keychain access is re-enabled.

Debug selection (debug menu enabled)

  • The Debug pane can force OAuth / Web / CLI.
  • Web extras are internal-only (not exposed in the Providers pane).

OAuth API (preferred)

  • Credentials:
    • CodexBar OAuth cache when available.
    • File fallback: ~/.claude/.credentials.json.
    • Claude CLI Keychain bootstrap/repair fallback: Claude Code-credentials.
  • Requires user:profile scope (CLI tokens with only user:inference cannot call usage).
  • Endpoint:
    • GET https://api.anthropic.com/api/oauth/usage
  • Headers:
    • Authorization: Bearer <access_token>
    • anthropic-beta: oauth-2025-04-20
  • Mapping:
    • five_hour → session window.
    • seven_day → weekly window; also becomes the primary fallback when five_hour is absent or has no utilization.
    • seven_day_sonnet / seven_day_opus → model-specific weekly window.
    • extra_usage → Extra usage cost (monthly spend/limit).
  • Successful OAuth login enables Claude and selects OAuth as the usage source.
  • Plan inference: subscriptionType is preferred when present; rate_limit_tier falls back to Max/Pro/Team/Enterprise.

Web API (cookies)

  • Preferences → Providers → Claude → Cookie source (Automatic or Manual).
  • Manual mode accepts a Cookie: header from a claude.ai request.
  • Multi-account manual tokens: add entries to ~/.codexbar/config.json (tokenAccounts) and set Claude cookies to Manual. The menu can show all accounts stacked or a switcher bar (Preferences → Advanced → Display).
  • Claude token accounts accept either sessionKey cookies or OAuth access tokens (sk-ant-oat...). OAuth-token accounts route to the OAuth path and disable cookie mode; session-key or cookie-header accounts stay in manual cookie mode. The exact edge-routing rules are documented in docs/refactor/claude-current-baseline.md.
  • Cookie source order:
    1. Safari: ~/Library/Cookies/Cookies.binarycookies
    2. Chrome/Chromium forks: ~/Library/Application Support/Google/Chrome/*/Cookies
    3. Firefox: ~/Library/Application Support/Firefox/Profiles/*/cookies.sqlite
  • Domain: claude.ai.
  • Cookie name required:
    • sessionKey (value prefix sk-ant-...).
  • Cached cookies: Keychain cache com.steipete.codexbar.cache (account cookie.claude, source + timestamp). Reused before re-importing from browsers.
  • API calls (all include Cookie: sessionKey=<value>):
    • GET https://claude.ai/api/organizations → org UUID.
    • GET https://claude.ai/api/organizations/{orgId}/usage → session/weekly/opus.
    • GET https://claude.ai/api/organizations/{orgId}/overage_spend_limit → Extra usage spend/limit.
    • GET https://claude.ai/api/account → email + plan hints.
  • Outputs:
    • Session + weekly + model-specific percent used.
    • Extra usage spend/limit (if enabled).
    • Account email + inferred plan.

CLI PTY (fallback)

  • Runs claude in a PTY session (ClaudeCLISession).
  • Default behavior: exit after each probe; Debug → "Keep CLI sessions alive" keeps it running between probes.
  • Command flow:
    1. Start CLI with --allowed-tools "" (no tools).
    2. Auto-respond to first-run prompts (trust files, workspace, telemetry).
    3. Send /usage, wait for rendered panel; send Enter retries if needed.
    4. Optionally send /status to extract identity fields.
  • Parsing (ClaudeStatusProbe):
    • Strips ANSI, locates "Current session" + "Current week" headers.
    • Extracts percent left/used and reset text near those headers.
    • Parses Account: and Org: lines when present.
    • Surfaces CLI errors (e.g. token expired) directly.

Cost usage (local log scan)

  • Source roots:
    • Native Claude logs:
      • $CLAUDE_CONFIG_DIR (comma-separated), each root uses <root>/projects.
      • Fallback roots:
        • ~/.config/claude/projects
        • ~/.claude/projects
    • Supported pi sessions:
      • ~/.pi/agent/sessions/**/*.jsonl
  • Files: **/*.jsonl under the native project roots plus supported pi session files.
  • Parsing:
    • Native Claude logs parse lines with type: "assistant" and message.usage.
    • Uses per-model token counts (input, cache read/create, output).
    • Deduplicates streaming chunks by message.id + requestId (usage is cumulative per chunk).
    • pi sessions attribute anthropic assistant usage to Claude and bucket it by assistant-turn timestamp, so a single pi session can contribute to multiple models/days.
  • Cache:
    • Native + merged provider cache: ~/Library/Caches/CodexBar/cost-usage/claude-v2.json
    • pi session cache: ~/Library/Caches/CodexBar/cost-usage/pi-sessions-v1.json

Key files

  • OAuth: Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/*
  • Web API: Sources/CodexBarCore/Providers/Claude/ClaudeWeb/ClaudeWebAPIFetcher.swift
  • CLI PTY: Sources/CodexBarCore/Providers/Claude/ClaudeStatusProbe.swift, Sources/CodexBarCore/Providers/Claude/ClaudeCLISession.swift
  • Cost usage: Sources/CodexBarCore/CostUsageFetcher.swift, Sources/CodexBarCore/PiSessionCostScanner.swift, Sources/CodexBarCore/PiSessionCostCache.swift, Sources/CodexBarCore/Vendored/CostUsage/*