GitHub Copilot Provider

Access GitHub Copilot models via OAuth Device Code flow - no browser required, works on headless servers.

Quick Start

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

First Run

Run ccs ghcp "your prompt"

Device Code Displayed

CCS displays verification URL and user code

Manual Authorization

Open URL in any browser, enter code manually

Token Received

CCS polls GitHub API, receives OAuth token when authorized

Token Cached

Token saved to ~/.ccs/cliproxy/auth/ghcp-{oauth}-{profile_id}.json

Device Code vs Browser OAuth

GHCP uses Device Code flow because GitHub Copilot OAuth does not support callback servers.

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

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

# 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

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

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

# ~/.ccs/config.yaml
copilot:
  account_type: "business"

Rate Limiting

GitHub Copilot has rate limits - configure behavior on limit:

Wait (Default)
Fail Fast

copilot:
  wait_on_limit: true

Behavior: CCS waits until rate limit resets, then retriesUse Case: Long-running sessions, non-interactive scripts

copilot:
  wait_on_limit: false

Behavior: CCS exits immediately with error on rate limitUse Case: Interactive sessions, user should know about limit

Custom Rate Limit Threshold:

copilot:
  rate_limit: 200   # Requests per hour (default: 100)

Environment Variables

Auto-managed by CCS. Manual override rarely needed.

# 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

# Execute with GitHub Copilot
ccs ghcp "your prompt"

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

Authentication Commands

# 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

# List accounts
ccs ghcp --accounts

# Switch account
ccs ghcp --use github-XYZ789

# Rename account
ccs ghcp --nickname work-copilot

Troubleshooting

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:

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:

# ~/.ccs/config.yaml
copilot:
  wait_on_limit: true   # Auto-wait for reset

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

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:

# ~/.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:

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:

{
  "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

CCS requests device code from GitHub API
GitHub returns:
- device_code (internal use)
- user_code (user enters in browser)
- verification_uri (URL to visit)
- interval (polling frequency)
User visits URL, enters code manually
CCS polls GitHub API every interval seconds
GitHub returns access token when user completes authorization
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:

Detect rate limit (429 response)
Read Retry-After header or calculate reset time
Display wait message with countdown
Sleep until reset (or user abort)
Retry request automatically

User Experience:

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:

Detect rate limit (429 response)
Display error message with reset time
Exit immediately with exit code 6 (PROVIDER_ERROR)

User Experience:

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

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:

# 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

Multi-Account Setup

Manage multiple GitHub accounts

Rate Limiting

Configure rate limit behavior

Device Code Flow

Understand headless authentication

CLIProxy Config

Advanced CLIProxy settings

Getting Started

Providers

Features

Tutorials

​GitHub Copilot Provider

​Quick Start

​Authentication

​Device Code Flow

​Device Code vs Browser OAuth

​Authentication Commands

​Multi-Account Support

​Account Identification

​Account Commands

​Configuration

​Config Keys

​Account Types

​Rate Limiting

​Environment Variables

​Commands Reference

​Basic Usage

​Authentication Commands

​Account Management

​Troubleshooting

​Device Code Expired

​Rate Limit Exceeded

​Wrong Account Type

​Token Refresh Failures

​Storage Locations

​Token Structure

​Device Code Flow Details

​Authorization Flow

​Polling Behavior

​No Callback Server Needed

​Rate Limiting Behavior

​Rate Limit Detection

​Wait Strategy

​Fail Fast Strategy

​Cost Information

​Advanced Features

​Model Mapping

​Account Registry Integration

​Session Persistence

​Next Steps

Multi-Account Setup

Rate Limiting

Device Code Flow

CLIProxy Config

GitHub Copilot Provider

Quick Start

Authentication

Device Code Flow

Device Code vs Browser OAuth

Authentication Commands

Multi-Account Support

Account Identification

Account Commands

Configuration

Config Keys

Account Types

Rate Limiting

Environment Variables

Commands Reference

Basic Usage

Authentication Commands

Account Management

Troubleshooting

Device Code Expired

Rate Limit Exceeded

Wrong Account Type

Token Refresh Failures

Storage Locations

Token Structure

Device Code Flow Details

Authorization Flow

Polling Behavior

No Callback Server Needed

Rate Limiting Behavior

Rate Limit Detection

Wait Strategy

Fail Fast Strategy

Cost Information

Advanced Features

Model Mapping

Account Registry Integration

Session Persistence

Next Steps