npm package: @franklin-ai/copilot-compat-proxy
Description: Turn GitHub Copilot into OpenAI/Anthropic API compatible server. Usable with Claude Code!
Author: Franklin Sun
Latest version: 1.0.13

# Copilot Compat Proxy

> [!WARNING]
> This is a reverse-engineered proxy of GitHub Copilot API. It is not supported by GitHub, and may break unexpectedly. Use at your own risk.

> [!WARNING]
> **GitHub Security Notice:**  
> Excessive automated or scripted use of Copilot (including rapid or bulk requests, such as via automated tools) may trigger GitHub's abuse-detection systems.  
> You may receive a warning from GitHub Security, and further anomalous activity could result in temporary suspension of your Copilot access.
>
> GitHub prohibits use of their servers for excessive automated bulk activity or any activity that places undue burden on their infrastructure.
>
> Please review:
>
> - [GitHub Acceptable Use Policies](https://docs.github.com/site-policy/acceptable-use-policies/github-acceptable-use-policies#4-spam-and-inauthentic-activity-on-github)
> - [GitHub Copilot Terms](https://docs.github.com/site-policy/github-terms/github-terms-for-additional-products-and-features#github-copilot)
>
> Use this proxy responsibly to avoid account restrictions.

---

## Project Overview

A reverse-engineered proxy for the GitHub Copilot API that exposes it as an OpenAI and Anthropic compatible service. This allows you to use GitHub Copilot with any tool that supports the OpenAI Chat Completions API or the Anthropic Messages API, including to power [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview).

## Features

- **OpenAI & Anthropic Compatibility**: Exposes GitHub Copilot as an OpenAI-compatible (`/v1/chat/completions`, `/v1/models`, `/v1/embeddings`) and Anthropic-compatible (`/v1/messages`) API.
- **Claude Code Integration**: Easily configure and launch [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) to use Copilot as its backend with a simple command-line flag (`--claude-code`).
- **Usage Dashboard**: A web-based dashboard to monitor your Copilot API usage, view quotas, and see detailed statistics.
- **Rate Limit Control**: Manage API usage with rate-limiting options (`--rate-limit`) and a waiting mechanism (`--wait`) to prevent errors from rapid requests.
- **Manual Request Approval**: Manually approve or deny each API request for fine-grained control over usage (`--manual`).
- **Token Visibility**: Option to display GitHub and Copilot tokens during authentication and refresh for debugging (`--show-token`).
- **Flexible Authentication**: Authenticate interactively or provide a GitHub token directly, suitable for CI/CD environments.
- **Support for Different Account Types**: Works with individual, business, and enterprise GitHub Copilot plans.

## Prerequisites

- [Bun](https://bun.sh/) (>= 1.2.x)
- GitHub account with Copilot subscription (individual, business, or enterprise)

## Quick Start

### Using npx

```sh
# Individual account (default)
npx @franklin-ai/copilot-compat-proxy@latest start

# Business account
npx @franklin-ai/copilot-compat-proxy@latest start --account-type business

# Enterprise account
npx @franklin-ai/copilot-compat-proxy@latest start --account-type enterprise
```

On first run, you'll be prompted to authenticate via GitHub Device Flow. Follow the on-screen instructions to log in.

### From Source

```sh
# Clone and install
git clone https://github.com/sunfulin123/copilot-api-proxy.git
cd copilot-api-proxy
bun install

# Development mode (with auto-reload)
bun run dev

# Production mode
bun run start
```

Pass options after `--`:

```sh
bun run dev -- --account-type business --verbose
```

### Using Docker

```sh
# Build image
docker build -t copilot-compat-proxy .

# Run with persistent token storage
mkdir -p ./copilot-data
docker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-compat-proxy

# Or pass GitHub token via environment variable
docker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-compat-proxy
```

Docker Compose:

```yaml
version: "3.8"
services:
  copilot-compat-proxy:
    build: .
    ports:
      - "4141:4141"
    environment:
      - GH_TOKEN=your_github_token_here
    restart: unless-stopped
```

## Command Structure

| Command       | Description                                                    |
| ------------- | -------------------------------------------------------------- |
| `start`       | Start the proxy server (handles authentication automatically)  |
| `auth`        | Run GitHub authentication flow only (no server)                |
| `check-usage` | Show current Copilot usage and quota in the terminal           |
| `debug`       | Display diagnostic info (version, runtime, paths, auth status) |

## Command Line Options

### start

| Option           | Description                                                   | Default      | Alias |
| ---------------- | ------------------------------------------------------------- | ------------ | ----- |
| `--port`         | Port to listen on                                             | `4141`       | `-p`  |
| `--verbose`      | Enable verbose logging                                        | `false`      | `-v`  |
| `--account-type` | Account type: `individual`, `business`, or `enterprise`       | `individual` | `-a`  |
| `--manual`       | Enable manual request approval                                | `false`      |       |
| `--rate-limit`   | Rate limit in seconds between requests                        |              | `-r`  |
| `--wait`         | Wait instead of error when rate limit is hit                  | `false`      | `-w`  |
| `--github-token` | Provide GitHub token directly (from `auth` subcommand)        |              | `-g`  |
| `--claude-code`  | Generate a command to launch Claude Code with proxy config    | `false`      | `-c`  |
| `--show-token`   | Show GitHub and Copilot tokens on fetch and refresh           | `false`      |       |
| `--proxy-env`    | Initialize proxy from environment variables                   | `false`      |       |

### auth

| Option         | Description               | Default | Alias |
| -------------- | ------------------------- | ------- | ----- |
| `--verbose`    | Enable verbose logging    | `false` | `-v`  |
| `--show-token` | Show GitHub token on auth | `false` |       |

### debug

| Option   | Description               | Default | Alias |
| -------- | ------------------------- | ------- | ----- |
| `--json` | Output debug info as JSON | `false` |       |

## API Endpoints

### OpenAI Compatible

| Endpoint                    | Method | Description            |
| --------------------------- | ------ | ---------------------- |
| `POST /v1/chat/completions` | POST   | Chat completions       |
| `GET /v1/models`            | GET    | List available models  |
| `POST /v1/embeddings`       | POST   | Create text embeddings |

### Anthropic Compatible

| Endpoint                         | Method | Description                   |
| -------------------------------- | ------ | ----------------------------- |
| `POST /v1/messages`              | POST   | Create message (Messages API) |
| `POST /v1/messages/count_tokens` | POST   | Count tokens for messages     |

### Monitoring

| Endpoint     | Method | Description                   |
| ------------ | ------ | ----------------------------- |
| `GET /usage` | GET    | Copilot usage and quota stats |
| `GET /token` | GET    | Current Copilot token         |

> All endpoints are also available without the `/v1/` prefix (e.g., `POST /chat/completions`).

## Using with Claude Code

### Interactive Setup

```sh
npx @franklin-ai/copilot-compat-proxy@latest start --claude-code
```

Select a primary model and a small/fast model when prompted. The launch command will be copied to your clipboard — paste it in a new terminal to start Claude Code.

### Manual Configuration

Create `.claude/settings.json` in your project root:

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:4141",
    "ANTHROPIC_AUTH_TOKEN": "dummy",
    "ANTHROPIC_MODEL": "claude-sonnet-4",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4",
    "ANTHROPIC_SMALL_FAST_MODEL": "gpt-4.1",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gpt-4.1",
    "DISABLE_NON_ESSENTIAL_MODEL_CALLS": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "permissions": {
    "deny": ["WebSearch"]
  }
}
```

> **Note:** The model names used here must be available in your Copilot account. Check available models via `curl http://localhost:4141/models | jq '.data[].id'` after starting the server.

See also: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables) | [IDE integration](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)

## Usage Viewer

After starting the server, a URL to the usage dashboard is displayed in the console:

```
https://ericc-ch.github.io/copilot-api?endpoint=http://localhost:4141/usage
```

The dashboard shows usage quotas, detailed statistics, and supports URL-based configuration for bookmarks.

On Windows, `start.bat` will open the dashboard automatically.

## Usage Tips

- **Rate limiting**: Use `--rate-limit 30` to enforce a 30-second gap between requests. Add `--wait` to make the server wait instead of returning an error.
- **Manual approval**: Use `--manual` to approve or deny each request individually.
- **Account type**: Business/Enterprise users **must** use `--account-type business` or `--account-type enterprise`. See [Troubleshooting](#using-with-businessenterprise-accounts) for details.
- **Proxy support**: Use `--proxy-env` to initialize proxy from `HTTP_PROXY` / `HTTPS_PROXY` environment variables.

## Troubleshooting

### Claude/Anthropic Models Not Available

If Claude models are enabled in your organization's Copilot settings but do not appear in the model list (or requests return `model_not_supported`), this is likely due to **IP-based geo-restriction**.

**Root Cause:** Anthropic does not serve certain regions (e.g., mainland China). GitHub Copilot records your IP address in the Copilot token (visible as `ip=x.x.x.x` in the token string) and filters out Anthropic models for restricted regions.

**How to verify:**

1. Start the server with `--show-token` and check the `ip=` field in the Copilot token.
2. If the IP belongs to a restricted region (e.g., China), Claude models will be filtered out.

**Solution:** Use a VPN with TUN (virtual network card) mode to route all traffic through a non-restricted region, then re-authenticate:

```sh
# 1. Enable VPN (TUN mode recommended to cover all traffic)
# 2. Delete the old token and re-authenticate
rm ~/.local/share/copilot-api/github_token
npx @franklin-ai/copilot-compat-proxy@latest start --account-type business --show-token

# 3. Verify the new token has a non-restricted IP in the ip= field
```

> **Important:** Keep VPN connected during use. The Copilot token refreshes periodically — if VPN is disconnected during a refresh, the new token will contain your real IP and Claude models will become unavailable again.

### Using with Business/Enterprise Accounts

For GitHub Copilot Business or Enterprise accounts, you **must** specify the account type:

```sh
# Business account
npx @franklin-ai/copilot-compat-proxy@latest start --account-type business

# Enterprise account
npx @franklin-ai/copilot-compat-proxy@latest start --account-type enterprise
```

Without this flag, requests are sent to the individual API endpoint (`api.githubcopilot.com`) instead of the correct business/enterprise endpoint (`api.business.githubcopilot.com`), resulting in missing models or authentication errors.

You can verify your account type by checking `https://api.github.com/copilot_internal/user` — the `copilot_plan` field shows your plan type, and the `endpoints.api` field shows the correct API endpoint.

### Checking Available Models

```sh
# After starting the server
curl http://localhost:4141/models | jq '.data[].id'
```

### Using Proxy for Network Issues

```sh
export HTTPS_PROXY=http://your-proxy:port
npx @franklin-ai/copilot-compat-proxy@latest start --account-type business --proxy-env
```