Skip to main content

​
Claude Provider

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

​
Quick Start

# First run (browser opens for OAuth)
ccs claude "explain this code"

# Use specific account
ccs claude --use work

# List all accounts
ccs claude --accounts

​
Authentication

​
Initial Setup

1

First Run

Run ccs claude "your prompt" - browser opens automatically
2

Claude OAuth

Sign in with your Claude account (requires Claude Pro/Max subscription)
3

Token Cached

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

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 second account (preserves existing)
ccs claude --auth --add

# Auto-nicknamed from email prefix
# john@gmail.com → "john"
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/api/provider/claude
ANTHROPIC_AUTH_TOKEN=ccs-internal-managed
ANTHROPIC_MODEL=claude-sonnet-4-5-20250929

​
Storage Locations

PathDescription
~/.ccs/cliproxy/auth/claude-*.jsonOAuth tokens (one per account)
~/.ccs/cliproxy/accounts.jsonAccount registry, nicknames
~/.ccs/cliproxy/config.yamlCLIProxy 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

Claude OAuth uses rolling quota windows that CCS tracks for automatic account rotation:
WindowDurationNotes
Short5 hoursPrimary rate limit window
Weekly7 daysSecondary quota window
Failover behavior: When a Claude OAuth account hits its quota, CCS automatically fails over to the next available account in the rotation (if multiple accounts configured). View quota status with: 
ccs cliproxy quota           # All providers including claude
ccs cliproxy status claude   # Claude-specific status

​
Cost Information

TierModelsCost
Claude ProClaude Opus 4.6, Opus 4.5, Sonnet 4.5, Sonnet 4, Haiku 4.5$20/month
Claude MaxAll Pro models (extended usage)$200/month
Claude provider requires an active Claude Pro or Max subscription. Free tier accounts are not supported.

​
Next Steps

Multi-Account Setup

Configure multiple Claude accounts

Provider Overview

Compare all available providers

Remote Proxy

Connect to external CLIProxy server