> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ccs.kaitran.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Provider

> Anthropic Claude OAuth provider with automatic token refresh and multi-account support

# Claude Provider

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

## Quick Start

```bash theme={null}
# 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

<Steps>
  <Step title="First Run">
    Run `ccs claude "your prompt"` - browser opens automatically
  </Step>

  <Step title="Claude OAuth">
    Sign in with your Claude account (requires Claude Pro/Max subscription)
  </Step>

  <Step title="Token Cached">
    OAuth token saved to `~/.ccs/cliproxy/auth/claude-{email}.json`
  </Step>

  <Step title="Auto Refresh">
    Token refreshes automatically 5 minutes before expiry
  </Step>
</Steps>

### 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:

```bash theme={null}
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:

<Tabs>
  <Tab title="Add Account">
    ```bash theme={null}
    # Add second account (preserves existing)
    ccs claude --auth --add

    # Auto-nicknamed from email prefix
    # john@gmail.com → "john"
    ```
  </Tab>

  <Tab title="List Accounts">
    ```bash theme={null}
    ccs claude --accounts

    # Output:
    # Available Claude accounts:
    # * john (john@gmail.com) - default
    #   work (alice@company.com)
    ```
  </Tab>

  <Tab title="Switch Account">
    ```bash theme={null}
    # Switch default account
    ccs claude --use work

    # Rename account
    ccs claude --nickname personal
    ```
  </Tab>
</Tabs>

**Account Registry:** `~/.ccs/cliproxy/accounts.json`

```json theme={null}
{
  "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

```bash theme={null}
# Execute with default model
ccs claude "your prompt"

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

### Authentication Commands

```bash theme={null}
# 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

```bash theme={null}
# 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`:

```yaml theme={null}
# CLIProxy settings
cliproxy:
  auth:
    api_key: "ccs-internal-managed"
    management_secret: "ccs"        # Dashboard login password
```

### Environment Variables

<Note>
  These are set automatically by CCS. Manual override rarely needed.
</Note>

```bash theme={null}
# 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:**

```json theme={null}
{
  "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:

```bash theme={null}
# 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:

```bash theme={null}
ccs claude --headless
# Copy URL to browser manually
```

### Multiple Accounts Confusion

**Symptom:** Wrong account being used

**Solution:** Check default account:

```bash theme={null}
# 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:

```bash theme={null}
ccs cliproxy quota           # All providers including claude
ccs cliproxy status claude   # Claude-specific status
```

<Note>
  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](/features/pool). That page covers the three-command setup,
  the slower turn right after a failover hop, leaving a pool, and migrating from
  native profiles.
</Note>

## 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 |

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

## 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:

```yaml theme={null}
# ~/.ccs/config.yaml
accounts:
  work:
    context_group: "team-alpha"
  work-backup:
    context_group: "team-alpha"
```

See [Claude Accounts](/providers/concepts/claude-accounts) for full details.

### Deeper Continuity

```bash theme={null}
# Maintain memory across sessions
ccs work --deeper-continuity "continue the refactor"
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Claude Accounts" icon="users" href="/providers/concepts/claude-accounts">
    Full guide to multiple Claude account management
  </Card>

  <Card title="Provider Overview" icon="sliders" href="/providers/concepts/overview">
    Compare all available providers
  </Card>

  <Card title="Remote Proxy" icon="server" href="/features/proxy/remote-proxy">
    Connect to external CLIProxy server
  </Card>

  <Card title="Configuration" icon="gear" href="/getting-started/configuration">
    Config file reference
  </Card>
</CardGroup>