Claude Provider

Access Anthropic Claude models via OAuth authentication with automatic token management and seamless multi-account support.

Quick Start

# Create named account and authenticate
ccs auth create work

# Use account by name
ccs work "explain this code"

# Or use the generic claude provider
ccs claude "explain this code"

# List all accounts
ccs claude --accounts

Authentication

Initial Setup

First Run

Run ccs claude "your prompt" - browser opens automatically

Claude OAuth

Token Cached

OAuth token saved to ~/.ccs/cliproxy/auth/claude-{email}.json

Auto Refresh

Token refreshes automatically 5 minutes before expiry

OAuth Flow Specifics

Authorization Code Flow:

Callback server spawns on port 54545
Browser opens for Claude OAuth consent
Token received via HTTP callback
Auto-refresh prevents mid-request failures

Proactive Token Refresh:

Checks expiry_date before each execution
Refreshes 5 minutes before expiry (matches CLIProxyAPI)
Prevents UND_ERR_SOCKET errors during long sessions
Graceful re-auth prompt if refresh fails

Headless Authentication

For servers without browser access:

ccs claude --headless

# Output:
# Open this URL on any device:
# https://claude.ai/oauth/authorize?...
#
# Waiting for authentication...

Complete OAuth on another device - CCS detects when token is cached.

Multi-Account Support

Manage multiple Claude accounts seamlessly:

Add Account
List Accounts
Switch Account

# Add second account (preserves existing)
ccs claude --auth --add

# Auto-nicknamed from email prefix
# john@gmail.com → "john"

ccs claude --accounts

# Output:
# Available Claude accounts:
# * john (john@gmail.com) - default
#   work (alice@company.com)

# Switch default account
ccs claude --use work

# Rename account
ccs claude --nickname personal

Anthropic OAuth allows a single email address to belong to multiple organizations (for example, a Personal organization and one or more Team/Enterprise organizations). When multiple organizations share the same email, CCS preserves each organization as a distinct account entry keyed by email#<org-hash> (e.g. john@example.com#a1b2c3d4):

Disambiguation: Because bare email selection is ambiguous, switch or manage accounts using either the assigned nickname or the full email#<hash> identifier:
ccs claude --use john-team # or ccs claude --use john@example.com#a1b2c3d4
Auto-pause & Quota Isolation: Auto-pause and cooldowns operate independently per organization without affecting sibling accounts that share the email. Account Registry: ~/.ccs/cliproxy/accounts.json

{
  "version": 1,
  "providers": {
    "claude": {
      "default": "john@gmail.com",
      "accounts": {
        "john@gmail.com": {
          "email": "john@gmail.com",
          "nickname": "john",
          "tokenFile": "claude-john@gmail.com.json",
          "createdAt": "2024-01-01T00:00:00Z",
          "lastUsedAt": "2024-01-05T12:00:00Z"
        }
      }
    }
  }
}

Commands Reference

Basic Usage

# Execute with default model
ccs claude "your prompt"

# One-shot mode (exit after response)
ccs claude "explain this function"

Authentication Commands

# Trigger OAuth (no session)
ccs claude --auth

# Add new account (preserves existing)
ccs claude --auth --add

# Logout (clear tokens)
ccs claude --logout

# Headless mode (no browser)
ccs claude --headless

Account Management

# List all accounts
ccs claude --accounts

# Switch default account
ccs claude --use work

# Rename current account
ccs claude --nickname personal

Configuration

Config Keys

Configure via ~/.ccs/config.yaml:

# CLIProxy settings
cliproxy:
  auth:
    api_key: "ccs-internal-managed"
    management_secret: "ccs"        # Dashboard login password

Environment Variables

These are set automatically by CCS. Manual override rarely needed.

# Claude CLI injection (auto-managed)
ANTHROPIC_BASE_URL=http://127.0.0.1:8317
ANTHROPIC_AUTH_TOKEN=ccs-internal-managed

Storage Locations

Path	Description
`~/.ccs/cliproxy/auth/claude-*.json`	OAuth tokens (one per account)
`~/.ccs/cliproxy/accounts.json`	Account registry, nicknames
`~/.ccs/cliproxy/config.yaml`	CLIProxy configuration

Requirements

Claude Pro or Claude Max subscription
Browser for OAuth (or --headless for servers)
Network access to Claude authentication servers

Token Management

Storage Format:

{
  "type": "claude",
  "access_token": "sk-ant-...",
  "refresh_token": "...",
  "email": "user@example.com",
  "expired": "2024-12-31T23:59:59Z",
  "expiry_date": 1735689599000
}

Auto-Refresh: Tokens refresh automatically 5 minutes before expiry Security: Tokens stored locally, never transmitted except to Anthropic

Troubleshooting

Token Refresh Failures

Symptom: UND_ERR_SOCKET errors during execution Cause: Token expired mid-request Solution: Proactive refresh handles this automatically. If issue persists:

# Clear and re-authenticate
ccs claude --logout
ccs claude --auth

Browser Doesn’t Open

Symptom: OAuth flow stuck waiting for browser Solution: Use headless mode:

ccs claude --headless
# Copy URL to browser manually

Multiple Accounts Confusion

Symptom: Wrong account being used Solution: Check default account:

# View all accounts (default marked with *)
ccs claude --accounts

# Switch default
ccs claude --use work

Quota Windows & Scoped Limits

Anthropic reports quota limits across multiple independent windows:

Window	Scope	Details
5-hour	General	Primary rate limit window for general account capacity
Weekly (All)	General	Account-wide weekly quota window
Weekly Scoped	Model-specific	Independent model-specific weekly limits (e.g. Fable or Opus)

Run ccs cliproxy quota --provider claude to inspect the windows Anthropic reports for each linked account.

Scoped Quota Semantics

Model Limit Isolation: Model-specific limits (such as Fable) do not lower general account health or automatically pause or rotate the entire account. An account with exhausted Fable quota remains available for Sonnet or Opus requests.
Partial Window Reports: Accounts can report a subset of windows (e.g. weekly only, or model limits only). Missing general windows remain treated as unknown rather than assumed healthy or exhausted.
Monetary Grants Excluded: Dollar-denominated credit grants (e.g. promotional credit buckets) are not treated as time-based quota rows.

To turn several Claude accounts into a pool that auto-continues a single conversation across the limit (fill-first plus session affinity), see Account Pools. That page covers the three-command setup, the slower turn right after a failover hop, leaving a pool, and migrating from native profiles.

Cost Information

Tier	Models	Cost
Claude Pro	Claude Opus 4.6, Opus 4.5, Sonnet 4.5, Sonnet 4, Haiku 4.5	$20/month
Claude Max	All Pro models (extended usage)	$200/month

Claude provider requires an active Claude Pro or Max subscription. Free tier accounts are not supported.

Advanced Features

Isolated Instances

Each named account (ccs auth create <name>) gets its own directory:

~/.ccs/instances/<name>/
├── .credentials.json   # OAuth credentials
├── session-env/        # Chat history
└── commands/           # Custom commands

This enables running two accounts simultaneously without session conflicts.

Shared Context Groups

Opt in to sharing context across accounts:

# ~/.ccs/config.yaml
accounts:
  work:
    context_group: "team-alpha"
  work-backup:
    context_group: "team-alpha"

See Claude Accounts for full details.

Deeper Continuity

# Maintain memory across sessions
ccs work --deeper-continuity "continue the refactor"

Next Steps

Claude Accounts

Full guide to multiple Claude account management

Provider Overview

Compare all available providers

Remote Proxy

Connect to external CLIProxy server

Configuration

Config file reference

Getting Started

Providers

Features

Tutorials

Claude Provider

Claude Provider

Quick Start

Authentication

Initial Setup

OAuth Flow Specifics

Headless Authentication

Multi-Account Support

Commands Reference

Basic Usage

Authentication Commands

Account Management

Configuration

Config Keys

Environment Variables

Storage Locations

Requirements

Token Management

Troubleshooting

Token Refresh Failures

Browser Doesn’t Open

Multiple Accounts Confusion

Quota Windows & Scoped Limits

Scoped Quota Semantics

Cost Information

Advanced Features

Isolated Instances

Shared Context Groups

Deeper Continuity

Next Steps

Claude Accounts

Provider Overview

Remote Proxy

Configuration

​Claude Provider

​Quick Start

​Authentication

​Initial Setup

​OAuth Flow Specifics

​Headless Authentication

​Multi-Account Support

​Organizations Sharing an Email

​Commands Reference

​Basic Usage

​Authentication Commands

​Account Management

​Configuration

​Config Keys

​Environment Variables

​Storage Locations

​Requirements

​Token Management

​Troubleshooting

​Token Refresh Failures

​Browser Doesn’t Open

​Multiple Accounts Confusion

​Quota Windows & Scoped Limits

​Scoped Quota Semantics

​Cost Information

​Advanced Features

​Isolated Instances

​Shared Context Groups

​Deeper Continuity

​Next Steps

Claude Accounts

Provider Overview

Remote Proxy

Configuration

Claude Provider

Quick Start

Authentication

Initial Setup

OAuth Flow Specifics

Headless Authentication

Multi-Account Support

Organizations Sharing an Email

Commands Reference

Basic Usage

Authentication Commands

Account Management

Configuration

Config Keys

Environment Variables

Storage Locations

Requirements

Token Management

Troubleshooting

Token Refresh Failures

Browser Doesn’t Open

Multiple Accounts Confusion

Quota Windows & Scoped Limits

Scoped Quota Semantics

Cost Information

Advanced Features

Isolated Instances

Shared Context Groups

Deeper Continuity

Next Steps