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

# GitHub Copilot Provider (Deprecated)

> Deprecated GitHub Copilot OAuth compatibility path with Device Code flow and rate limiting

# GitHub Copilot Provider (Deprecated)

Access GitHub Copilot models via OAuth Device Code flow for existing local
setups. This provider is now a deprecated compatibility path.

<Warning>
  GitHub usage-based Copilot billing begins June 1, 2026. Existing CCS Copilot
  setups remain available for compatibility, but new setups should prefer Codex
  or another active provider.
</Warning>

## Compatibility Quick Start

```bash theme={null}
# First run (Device Code flow - no browser needed)
ccs ghcp "explain this code"

# Output:
# Visit: https://github.com/login/device
# Enter code: ABCD-1234
# Waiting for authorization...
```

## Authentication

### Device Code Flow

GitHub Copilot uses **Device Code flow** instead of browser OAuth - ideal for headless servers and remote machines.

<Steps>
  <Step title="First Run">
    Run `ccs ghcp "your prompt"`
  </Step>

  <Step title="Device Code Displayed">
    CCS displays verification URL and user code
  </Step>

  <Step title="Manual Authorization">
    Open URL in any browser, enter code manually
  </Step>

  <Step title="Token Received">
    CCS polls GitHub API, receives OAuth token when authorized
  </Step>

  <Step title="Token Cached">
    Token saved to `~/.ccs/cliproxy/auth/ghcp-{oauth}-{profile_id}.json`
  </Step>
</Steps>

<Note>Available since v7.37.1 - Device code and verification URL are also displayed in the CCS Dashboard for convenient access during authentication.</Note>

**Dashboard Display:**

* Device code shown with copy button
* Verification URL as clickable link
* 15-minute expiration timer countdown
* Auto-refresh on successful authorization

### Device Code vs Browser OAuth

<Note>
  GHCP uses Device Code flow because GitHub Copilot OAuth **does not support** callback servers.
</Note>

| Feature           | Device Code (GHCP)            | Browser OAuth (Gemini/Codex) |
| ----------------- | ----------------------------- | ---------------------------- |
| Browser required? | No - works headless           | Yes - opens automatically    |
| User action       | Copy code to browser manually | Click "Allow" in popup       |
| Headless support  | Native                        | Requires `--headless` flag   |
| Callback server   | None - polling only           | Spawns local HTTP server     |

### Authentication Commands

```bash theme={null}
# Trigger Device Code flow
ccs ghcp --auth

# Output:
# Visit: https://github.com/login/device
# Enter code: ABCD-1234
# Code expires in 15 minutes
# Waiting for authorization...
```

Complete authorization in any browser on any device - CCS polls GitHub API for token.

## Multi-Account Support

GitHub Copilot supports multiple accounts with **filename-based** identification:

```bash theme={null}
# Add second account
ccs ghcp --auth --add

# List accounts
ccs ghcp --accounts

# Output:
# Available GitHub Copilot accounts:
# * github-ABC123 (default)
#   github-XYZ789
```

### Account Identification

**Pattern:** `ghcp-{oauth}-{profile_id}.json` → `{oauth}-{profile_id}`

**Example:**

* Token file: `ghcp-github-ABC123.json`
* Account ID: `github-ABC123`
* Nickname: Auto-generated or custom via `--nickname`

### Account Commands

```bash theme={null}
# Switch default account
ccs ghcp --use github-XYZ789

# Rename account
ccs ghcp --nickname work-copilot

# List all accounts
ccs ghcp --accounts

# Logout (clear tokens)
ccs ghcp --logout
```

## Configuration

### Config Keys

Configure via `~/.ccs/config.yaml`:

```yaml theme={null}
# GitHub Copilot settings
copilot:
  account_type: "individual"    # or "business"
  rate_limit: 100               # Requests per hour
  wait_on_limit: true           # Wait vs fail on rate limit

# CLIProxy auth
cliproxy:
  auth:
    api_key: "ccs-internal-managed"
    management_secret: "ccs"
```

### Account Types

| Type         | Use Case                      | Rate Limits     |
| ------------ | ----------------------------- | --------------- |
| `individual` | Personal Copilot subscription | Standard limits |
| `business`   | GitHub Copilot for Business   | Higher limits   |

**Set account type:**

```yaml theme={null}
# ~/.ccs/config.yaml
copilot:
  account_type: "business"
```

### Rate Limiting

GitHub Copilot has rate limits - configure behavior on limit:

<Tabs>
  <Tab title="Wait (Default)">
    ```yaml theme={null}
    copilot:
      wait_on_limit: true
    ```

    **Behavior:** CCS waits until rate limit resets, then retries

    **Use Case:** Long-running sessions, non-interactive scripts
  </Tab>

  <Tab title="Fail Fast">
    ```yaml theme={null}
    copilot:
      wait_on_limit: false
    ```

    **Behavior:** CCS exits immediately with error on rate limit

    **Use Case:** Interactive sessions, user should know about limit
  </Tab>
</Tabs>

**Custom Rate Limit Threshold:**

```yaml theme={null}
copilot:
  rate_limit: 200   # Requests per hour (default: 100)
```

### Environment Variables

<Note>
  Auto-managed by CCS. Manual override rarely needed.
</Note>

```bash theme={null}
# Claude CLI injection (auto-set)
ANTHROPIC_BASE_URL=http://127.0.0.1:8317/api/provider/ghcp
ANTHROPIC_AUTH_TOKEN=ccs-internal-managed
ANTHROPIC_MODEL=ghcp-default   # Model mapping handled by CLIProxy
```

## Commands Reference

### Basic Usage

```bash theme={null}
# Execute with GitHub Copilot
ccs ghcp "your prompt"

# One-shot mode
ccs ghcp "explain this function"
```

### Authentication Commands

```bash theme={null}
# Trigger Device Code flow
ccs ghcp --auth

# Add new account
ccs ghcp --auth --add

# Logout
ccs ghcp --logout

# No --headless flag needed (Device Code is headless-native)
```

### Account Management

```bash theme={null}
# List accounts
ccs ghcp --accounts

# Switch account
ccs ghcp --use github-XYZ789

# Rename account
ccs ghcp --nickname work-copilot
```

## Troubleshooting

### Improved OAuth Failure Diagnostics

<Note>Available since v7.51.0</Note>

CCS now provides specific, actionable error messages when GitHub Copilot OAuth fails — instead of generic "Token not found" errors.

**Before v7.51:** All auth failures showed `Token not found`

**After v7.51:** Specific errors surfaced from GitHub's OAuth flow:

| Error                    | Meaning                            | Action                        |
| ------------------------ | ---------------------------------- | ----------------------------- |
| `authorization_pending`  | User hasn't completed login yet    | Wait and retry                |
| `slow_down`              | Polling too fast                   | CCS handles automatically     |
| `expired_token`          | Device code expired (15 min limit) | Re-run `ccs ghcp --auth`      |
| `access_denied`          | User denied the authorization      | Re-run and approve in browser |
| `unsupported_grant_type` | OAuth config issue                 | Contact support               |

CCS strips ANSI escape codes and parses multi-line stderr from the GitHub OAuth flow, so errors from nested processes are surfaced cleanly in the terminal.

### Device Code Expired

**Symptom:** "Device code expired" error during authorization

**Cause:** User didn't complete authorization within 15 minutes

**Solution:** Re-run `--auth` to get new code:

```bash theme={null}
ccs ghcp --auth
# Complete authorization within 15 minutes
```

### Rate Limit Exceeded

**Symptom:** `429 Too Many Requests` error

**Cause:** Exceeded GitHub Copilot rate limit

**Solution 1:** Wait for rate limit reset (if `wait_on_limit: true`)

**Solution 2:** Configure wait behavior:

```yaml theme={null}
# ~/.ccs/config.yaml
copilot:
  wait_on_limit: true   # Auto-wait for reset
```

**Solution 3:** Increase rate limit threshold (Business accounts):

```yaml theme={null}
copilot:
  rate_limit: 200   # Higher limit for Business tier
```

### Wrong Account Type

**Symptom:** Unexpected rate limits or quota errors

**Cause:** Account type mismatch (Individual vs Business)

**Solution:** Set correct account type:

```yaml theme={null}
# ~/.ccs/config.yaml
copilot:
  account_type: "business"   # or "individual"
```

### Token Refresh Failures

**Symptom:** "Unauthorized" errors after initial auth

**Cause:** OAuth token expired, refresh failed

**Solution:** Re-authenticate:

```bash theme={null}
ccs ghcp --auth
```

## Storage Locations

| Path                               | Description                                  |
| ---------------------------------- | -------------------------------------------- |
| `~/.ccs/cliproxy/auth/ghcp-*.json` | OAuth tokens (one per account)               |
| `~/.ccs/cliproxy/accounts.json`    | Account registry, nicknames                  |
| `~/.ccs/cliproxy/config.yaml`      | CLIProxy configuration                       |
| `~/.ccs/config.yaml`               | Copilot settings (rate limits, account type) |

## Token Structure

GitHub Copilot OAuth token file format:

```json theme={null}
{
  "type": "github-copilot",
  "access_token": "gho_...",
  "refresh_token": "ghr_...",
  "expired": "2024-12-31T23:59:59Z"
}
```

**Filename Pattern:** `ghcp-{oauth}-{profile_id}.json`

**Account Identification:** Extracted from filename (no email field)

## Device Code Flow Details

### Authorization Flow

1. **CCS requests device code** from GitHub API
2. **GitHub returns:**
   * `device_code` (internal use)
   * `user_code` (user enters in browser)
   * `verification_uri` (URL to visit)
   * `interval` (polling frequency)
3. **User visits URL**, enters code manually
4. **CCS polls GitHub API** every `interval` seconds
5. **GitHub returns access token** when user completes authorization
6. **CCS caches token** to auth directory

### Polling Behavior

* **Interval:** 5 seconds (default from GitHub API)
* **Timeout:** 15 minutes (device code expiry)
* **Retry:** Stops on authorization or expiry

### No Callback Server Needed

Device Code flow eliminates need for:

* Local HTTP server
* Port availability
* Firewall configuration
* Localhost access

**Perfect for:**

* Headless servers
* Remote SSH sessions
* Docker containers
* CI/CD pipelines

## Rate Limiting Behavior

### Rate Limit Detection

CLIProxyAPI detects rate limits via:

* HTTP 429 status code
* `X-RateLimit-Remaining: 0` header
* `Retry-After` header

### Wait Strategy

When `wait_on_limit: true`:

1. **Detect rate limit** (429 response)
2. **Read `Retry-After` header** or calculate reset time
3. **Display wait message** with countdown
4. **Sleep until reset** (or user abort)
5. **Retry request** automatically

**User Experience:**

```bash theme={null}
ccs ghcp "long prompt"

# Output:
# [!] Rate limit exceeded
# [i] Waiting 47 minutes until reset at 14:30:00
# Press Ctrl+C to cancel
```

### Fail Fast Strategy

When `wait_on_limit: false`:

1. **Detect rate limit** (429 response)
2. **Display error message** with reset time
3. **Exit immediately** with exit code 6 (`PROVIDER_ERROR`)

**User Experience:**

```bash theme={null}
ccs ghcp "prompt"

# Output:
# [X] Rate limit exceeded
# [i] Limit resets at 14:30:00 (in 47 minutes)
# [i] Set copilot.wait_on_limit: true to auto-wait
```

## Quota Information

CCS tracks GitHub Copilot quota via `ccs cliproxy quota` and `ccs copilot usage`:

```bash theme={null}
ccs copilot usage

# Output:
# GitHub Copilot Usage
#   Premium interactions: 42 / 300
#   Chat:                 128 / 500
#   Completions:          2341 / unlimited
#   Plan:                 individual
#   Quota resets:         2026-03-01
```

| Quota Type            | Description                                  |
| --------------------- | -------------------------------------------- |
| `premiumInteractions` | High-capability model requests (Opus, GPT-5) |
| `chat`                | Chat completions requests                    |
| `completions`         | Code completions (usually unlimited)         |

**Reset period:** Monthly (shown in `ccs copilot usage` output)

## Cost Information

| Tier       | Cost            | Rate Limits     |
| ---------- | --------------- | --------------- |
| Individual | \$10/month      | Standard limits |
| Business   | \$19/user/month | Higher limits   |
| Enterprise | Custom pricing  | Custom limits   |

**Rate Limits:**

* Individual: \~100 requests/hour
* Business: \~200 requests/hour (configurable)
* Exact limits set by GitHub, vary by account

## Advanced Features

### Model Mapping

GitHub Copilot models are mapped to Claude model IDs internally by CLIProxyAPI:

```bash theme={null}
# Claude requests "claude-opus-4-5"
# CLIProxyAPI routes to GitHub Copilot equivalent
```

**User does NOT need to specify model** - routing is automatic.

### Account Registry Integration

GHCP uses same multi-account system as other OAuth providers:

* Accounts stored in `~/.ccs/cliproxy/accounts.json`
* Nicknames auto-generated from account ID
* Default account tracked per provider
* `lastUsedAt` timestamp for analytics

### Session Persistence

GitHub Copilot sessions benefit from CLIProxy session persistence:

* First `ccs ghcp` spawns proxy (1-2s startup)
* Subsequent commands reuse existing proxy (instant)
* Proxy terminates when last session exits
* Version mismatch detection → auto-restart on upgrade

## Next Steps

<CardGroup cols={2}>
  <Card title="Multi-Account Setup" icon="users" href="/providers/concepts/overview#multi-account-management">
    Manage multiple GitHub accounts
  </Card>

  <Card title="Rate Limiting" icon="gauge" href="/providers/oauth/ghcp#rate-limiting">
    Configure rate limit behavior
  </Card>

  <Card title="Device Code Flow" icon="mobile" href="/providers/oauth/ghcp#device-code-flow">
    Understand headless authentication
  </Card>

  <Card title="CLIProxy Config" icon="gear" href="/reference/config-schema">
    Advanced CLIProxy settings
  </Card>
</CardGroup>