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
Sign in with your Claude account (requires Claude Pro/Max subscription)
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/api/provider/claude ANTHROPIC_AUTH_TOKEN = ccs-internal-managed ANTHROPIC_MODEL = claude-sonnet-4-5-20250929
Storage Locations Path Description ~/.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 expirySecurity: Tokens stored locally, never transmitted except to AnthropicTroubleshooting Token Refresh Failures Symptom: UND_ERR_SOCKET errors during executionCause: Token expired mid-requestSolution: 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 browserSolution: Use headless mode:ccs claude --headless # Copy URL to browser manually
Multiple Accounts Confusion Symptom: Wrong account being usedSolution: 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
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
