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

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

Claude OAuth uses rolling quota windows that CCS tracks for automatic account rotation:

Window	Duration	Notes
Short	5 hours	Primary rate limit window
Weekly	7 days	Secondary 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

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

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

​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

​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

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

Cost Information

Advanced Features

Isolated Instances

Shared Context Groups

Deeper Continuity

Next Steps