xc-copilot-api 1.2.2 → 1.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +160 -342
  2. package/dist/main.js +22 -5
  3. package/dist/main.js.map +1 -1
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -8,202 +8,169 @@
8
8
 
9
9
  > [!WARNING]
10
10
  > **GitHub Security Notice:**
11
- > Excessive automated or scripted use of Copilot (including rapid or bulk requests, such as via automated tools) may trigger GitHub's abuse-detection systems.
12
- > You may receive a warning from GitHub Security, and further anomalous activity could result in temporary suspension of your Copilot access.
13
- >
14
- > GitHub prohibits use of their servers for excessive automated bulk activity or any activity that places undue burden on their infrastructure.
15
- >
16
- > Please review:
11
+ > Excessive automated or scripted use of Copilot (including rapid or bulk requests, such as via automated tools) may trigger GitHub's abuse-detection systems. Use this proxy responsibly to avoid account restrictions.
17
12
  >
18
13
  > - [GitHub Acceptable Use Policies](https://docs.github.com/site-policy/acceptable-use-policies/github-acceptable-use-policies#4-spam-and-inauthentic-activity-on-github)
19
14
  > - [GitHub Copilot Terms](https://docs.github.com/site-policy/github-terms/github-terms-for-additional-products-and-features#github-copilot)
20
- >
21
- > Use this proxy responsibly to avoid account restrictions.
22
15
 
23
16
  [![爱发电](https://img.shields.io/badge/爱发电-billxc-946ce6?style=for-the-badge)](https://afdian.com/a/billxc)
24
17
 
25
- ---
18
+ A reverse-engineered proxy for the GitHub Copilot API that exposes it as an OpenAI and Anthropic compatible service. Use GitHub Copilot with [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), [Codex CLI](https://github.com/openai/codex), or any tool that supports the OpenAI / Anthropic API.
26
19
 
27
- **Note:** If you are using [opencode](https://github.com/sst/opencode), you do not need this project. Opencode supports GitHub Copilot provider out of the box.
20
+ > **Note:** If you are using [opencode](https://github.com/sst/opencode), you do not need this project. Opencode supports GitHub Copilot provider out of the box.
28
21
 
29
- ---
22
+ ## Quick Start
30
23
 
31
- ## Project Overview
32
-
33
- 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).
24
+ ```sh
25
+ # 1. Start the server
26
+ npx xc-copilot-api@latest start
34
27
 
35
- ## Features
28
+ # 2. Configure your tool
29
+ npx xc-copilot-api@latest config --claude # Claude Code (Opus 4.7)
30
+ npx xc-copilot-api@latest config --codex # Codex CLI (GPT-5.5)
31
+ ```
36
32
 
37
- - **OpenAI & Anthropic Compatibility**: Exposes GitHub Copilot as an OpenAI-compatible (`/v1/chat/completions`, `/v1/models`, `/v1/embeddings`) and Anthropic-compatible (`/v1/messages`) API.
38
- - **Claude Code & Codex CLI Integration**: Configure [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) or Codex CLI to use Copilot as backend with `config --claude` or `config --codex`.
39
- - **Usage Dashboard**: A web-based dashboard to monitor your Copilot API usage, view quotas, and see detailed statistics.
40
- - **Rate Limit Control**: Manage API usage with rate-limiting options (`--rate-limit`) and a waiting mechanism (`--wait`) to prevent errors from rapid requests.
41
- - **Manual Request Approval**: Manually approve or deny each API request for fine-grained control over usage (`--manual`).
42
- - **Token Visibility**: Option to display GitHub and Copilot tokens during authentication and refresh for debugging (`--show-token`).
43
- - **Flexible Authentication**: Authenticate interactively or provide a GitHub token directly, suitable for CI/CD environments.
44
- - **Support for Different Account Types**: Works with individual, business, and enterprise GitHub Copilot plans.
33
+ That's it. Your tool is now powered by GitHub Copilot.
45
34
 
46
35
  ## Demo
47
36
 
48
37
  https://github.com/user-attachments/assets/7654b383-669d-4eb9-b23c-06d7aefee8c5
49
38
 
50
- ## Prerequisites
51
-
52
- - Bun (>= 1.2.x)
53
- - GitHub account with Copilot subscription (individual, business, or enterprise)
54
-
55
- ## Installation
56
-
57
- To install dependencies, run:
58
-
59
- ```sh
60
- bun install
61
- ```
62
-
63
- ## Using with Docker
39
+ ## Features
64
40
 
65
- ### Using Pre-built Image from GitHub Container Registry
41
+ - **OpenAI & Anthropic Compatibility** — `/v1/chat/completions`, `/v1/responses`, `/v1/messages`, `/v1/embeddings`, `/v1/models`
42
+ - **Native Passthrough** — Claude and GPT models are forwarded directly to upstream with full protocol fidelity (tool use, streaming, thinking blocks, vision)
43
+ - **One-command Setup** — `config --claude` / `config --codex` writes the right settings automatically
44
+ - **Usage Dashboard** — Web UI to monitor quotas and usage statistics
45
+ - **Rate Limiting** — `--rate-limit` and `--wait` to stay within GitHub's limits
46
+ - **Background Service** — Run as a system service via [easy-service](https://github.com/billxc/easy-service)
47
+ - **Multiple Account Types** — Individual, business, and enterprise Copilot plans
66
48
 
67
- You can pull and run the pre-built image directly from GitHub Container Registry:
49
+ ## Using with Claude Code
68
50
 
69
51
  ```sh
70
- # Pull the latest image
71
- docker pull ghcr.io/billxc/copilot-api:latest
72
-
73
- # Create a directory on your host to persist the GitHub token and related data
74
- mkdir -p ./copilot-data
52
+ # Opus 4.7 (default)
53
+ npx xc-copilot-api@latest config --claude
75
54
 
76
- # Run the container with a bind mount to persist the token
77
- docker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api ghcr.io/billxc/copilot-api:latest
55
+ # Opus 4.6
56
+ npx xc-copilot-api@latest config --claude -m 4.6
78
57
  ```
79
58
 
80
- Available tags:
81
- - `latest` - Latest build from the master branch
82
- - `v*.*.*` - Specific version tags (e.g., `v1.0.0`)
83
- - `master` - Latest master branch build
84
- - `<sha>` - Specific commit builds
59
+ A backup of your existing config is saved as `settings.json.bak`.
85
60
 
86
- ### Building Locally
61
+ <details>
62
+ <summary>Manual configuration</summary>
87
63
 
88
- Build image from source:
64
+ **Opus 4.7 (default):**
89
65
 
90
- ```sh
91
- docker build -t copilot-api .
66
+ ```json
67
+ {
68
+ "env": {
69
+ "ANTHROPIC_BASE_URL": "http://localhost:4141",
70
+ "ANTHROPIC_AUTH_TOKEN": "Powered by xc copilot",
71
+ "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4.7-1m-internal",
72
+ "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
73
+ }
74
+ }
92
75
  ```
93
76
 
94
- Run the locally built container:
95
-
96
- ```sh
97
- # Create a directory on your host to persist the GitHub token and related data
98
- mkdir -p ./copilot-data
99
-
100
- # Run the container with a bind mount to persist the token
101
- # This ensures your authentication survives container restarts
77
+ **Opus 4.6:**
102
78
 
103
- docker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api
79
+ ```json
80
+ {
81
+ "env": {
82
+ "ANTHROPIC_BASE_URL": "http://localhost:4141",
83
+ "ANTHROPIC_AUTH_TOKEN": "Powered by xc copilot",
84
+ "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4.6-1m",
85
+ "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
86
+ }
87
+ }
104
88
  ```
105
89
 
106
- > **Note:**
107
- > The GitHub token and related data will be stored in `copilot-data` on your host. This is mapped to `/root/.local/share/copilot-api` inside the container, ensuring persistence across restarts.
90
+ More options: [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)
108
91
 
109
- ### Docker with Environment Variables
92
+ </details>
110
93
 
111
- You can pass the GitHub token directly to the container using environment variables:
94
+ ## Using with Codex CLI
112
95
 
113
96
  ```sh
114
- # Build with GitHub token
115
- docker build --build-arg GH_TOKEN=your_github_token_here -t copilot-api .
116
-
117
- # Run with GitHub token
118
- docker run -p 4141:4141 -e GH_TOKEN=your_github_token_here copilot-api
119
-
120
- # Run with additional options
121
- docker run -p 4141:4141 -e GH_TOKEN=your_token copilot-api start --verbose --port 4141
97
+ npx xc-copilot-api@latest config --codex
122
98
  ```
123
99
 
124
- ### Docker Compose Example
125
-
126
- Using pre-built image:
100
+ <details>
101
+ <summary>Manual configuration</summary>
127
102
 
128
- ```yaml
129
- version: "3.8"
130
- services:
131
- copilot-api:
132
- image: ghcr.io/billxc/copilot-api:latest
133
- ports:
134
- - "4141:4141"
135
- environment:
136
- - GH_TOKEN=your_github_token_here
137
- volumes:
138
- - ./copilot-data:/root/.local/share/copilot-api
139
- restart: unless-stopped
140
- ```
103
+ Add to `~/.codex/config.toml`:
141
104
 
142
- Or building from source:
105
+ ```toml
106
+ model = "gpt-5.5"
107
+ model_provider = "copilot-api"
143
108
 
144
- ```yaml
145
- version: "3.8"
146
- services:
147
- copilot-api:
148
- build: .
149
- ports:
150
- - "4141:4141"
151
- environment:
152
- - GH_TOKEN=your_github_token_here
153
- volumes:
154
- - ./copilot-data:/root/.local/share/copilot-api
155
- restart: unless-stopped
109
+ [model_providers.copilot-api]
110
+ name = "copilot-api"
111
+ base_url = "http://localhost:4141/v1"
112
+ wire_api = "responses"
156
113
  ```
157
114
 
158
- The Docker image includes:
115
+ </details>
159
116
 
160
- - Multi-stage build for optimized image size
161
- - Non-root user for enhanced security
162
- - Health check for container monitoring
163
- - Pinned base image version for reproducible builds
117
+ ## Command Reference
164
118
 
165
- ## Using with npx
119
+ ### Commands
166
120
 
167
- You can run the project directly using npx:
121
+ | Command | Description |
122
+ | ------------- | ------------------------------------------------------------------ |
123
+ | `start` | Start the API server (handles auth automatically) |
124
+ | `auth` | Run GitHub auth flow only (for generating tokens for CI/CD) |
125
+ | `config` | Configure Claude Code or Codex CLI to use this proxy |
126
+ | `check-usage` | Show Copilot usage and quota in the terminal |
127
+ | `debug` | Display version, runtime, file paths, and auth status |
168
128
 
169
- ```sh
170
- npx xc-copilot-api@latest start
171
- ```
129
+ ### `start` Options
172
130
 
173
- With options:
131
+ | Option | Description | Default | Alias |
132
+ | -------------- | ------------------------------------------------------ | ---------- | ----- |
133
+ | --port | Port to listen on | 4141 | -p |
134
+ | --verbose | Enable verbose logging | false | -v |
135
+ | --account-type | Account type (individual, business, enterprise) | individual | -a |
136
+ | --manual | Manually approve each request | false | |
137
+ | --rate-limit | Minimum seconds between requests | | -r |
138
+ | --wait | Wait instead of error when rate limited | false | -w |
139
+ | --github-token | Provide GitHub token directly | | -g |
140
+ | --show-token | Show tokens on fetch and refresh | false | |
141
+ | --proxy-env | Initialize proxy from environment variables | false | |
174
142
 
175
- ```sh
176
- npx xc-copilot-api@latest start --port 8080
177
- ```
143
+ ### `config` Options
178
144
 
179
- For authentication only:
145
+ | Option | Description | Default | Alias |
146
+ | -------------- | ------------------------------------------------- | ------- | ----- |
147
+ | --claude | Configure Claude Code (`~/.claude/settings.json`) | false | -c |
148
+ | --codex | Configure Codex CLI (`~/.codex/config.toml`) | false | -x |
149
+ | --claude-model | Claude Opus model version (4.7 or 4.6) | 4.7 | -m |
180
150
 
181
- ```sh
182
- npx xc-copilot-api@latest auth
183
- ```
184
-
185
- ## Command Structure
186
-
187
- Copilot API now uses a subcommand structure with these main commands:
188
-
189
- - `start`: Start the Copilot API server. This command will also handle authentication if needed.
190
- - `auth`: Run GitHub authentication flow without starting the server. This is typically used if you need to generate a token for use with the `--github-token` option, especially in non-interactive environments.
191
- - `config`: Configure external AI tools (Claude Code, Codex CLI) to use Copilot API.
192
- - `check-usage`: Show your current GitHub Copilot usage and quota information directly in the terminal (no server required).
193
- - `debug`: Display diagnostic information including version, runtime details, file paths, and authentication status. Useful for troubleshooting and support.
151
+ ## API Endpoints
194
152
 
195
- ### Running as a Background Service
153
+ | Endpoint | Description |
154
+ | -------------------------------- | ---------------------------------------------- |
155
+ | `POST /v1/chat/completions` | OpenAI Chat Completions API |
156
+ | `POST /v1/responses` | OpenAI Responses API (native passthrough) |
157
+ | `POST /v1/messages` | Anthropic Messages API (native passthrough) |
158
+ | `POST /v1/messages/count_tokens` | Anthropic token counting |
159
+ | `GET /v1/models` | List available models |
160
+ | `POST /v1/embeddings` | Create embedding vectors |
161
+ | `GET /usage` | Copilot usage statistics and quota |
162
+ | `GET /token` | Current Copilot token |
196
163
 
197
- Use [easy-service](https://github.com/billxc/easy-service) to run as a background service on macOS, Linux, and Windows:
164
+ ## Running as a Background Service
198
165
 
199
166
  ```bash
200
167
  # Install easy-service
201
168
  uv tool install git+https://github.com/billxc/easy-service.git
202
169
 
203
- # Install and start the service
170
+ # Install and start
204
171
  easy-service install copilot-api -- npx -y xc-copilot-api@latest start
205
172
 
206
- # Manage the service
173
+ # Manage
207
174
  easy-service status copilot-api
208
175
  easy-service logs copilot-api -f
209
176
  easy-service restart copilot-api
@@ -211,242 +178,93 @@ easy-service stop copilot-api
211
178
  easy-service uninstall copilot-api
212
179
  ```
213
180
 
214
- ## Command Line Options
215
-
216
- ### Start Command Options
217
-
218
- The following command line options are available for the `start` command:
219
-
220
- | Option | Description | Default | Alias |
221
- | -------------- | ----------------------------------------------------------------------------- | ---------- | ----- |
222
- | --port | Port to listen on | 4141 | -p |
223
- | --verbose | Enable verbose logging | false | -v |
224
- | --account-type | Account type to use (individual, business, enterprise) | individual | -a |
225
- | --manual | Enable manual request approval | false | none |
226
- | --rate-limit | Rate limit in seconds between requests | none | -r |
227
- | --wait | Wait instead of error when rate limit is hit | false | -w |
228
- | --github-token | Provide GitHub token directly (must be generated using the `auth` subcommand) | none | -g |
229
- | --show-token | Show GitHub and Copilot tokens on fetch and refresh | false | none |
230
- | --proxy-env | Initialize proxy from environment variables | false | none |
231
-
232
- ### Config Command Options
233
-
234
- | Option | Description | Default | Alias |
235
- | ------- | ------------------------------------------------- | ------- | ----- |
236
- | --claude | Configure Claude Code (`~/.claude/settings.json`) | false | -c |
237
- | --codex | Configure Codex CLI (`~/.codex/config.toml`) | false | -x |
238
-
239
- ### Auth Command Options
240
-
241
- | Option | Description | Default | Alias |
242
- | ------------ | ------------------------- | ------- | ----- |
243
- | --verbose | Enable verbose logging | false | -v |
244
- | --show-token | Show GitHub token on auth | false | none |
245
-
246
- ### Debug Command Options
247
-
248
- | Option | Description | Default | Alias |
249
- | ------ | ------------------------- | ------- | ----- |
250
- | --json | Output debug info as JSON | false | none |
251
-
252
- ## API Endpoints
253
-
254
- The server exposes several endpoints to interact with the Copilot API. It provides OpenAI-compatible endpoints and now also includes support for Anthropic-compatible endpoints, allowing for greater flexibility with different tools and services.
255
-
256
- ### OpenAI Compatible Endpoints
257
-
258
- These endpoints mimic the OpenAI API structure.
259
-
260
- | Endpoint | Method | Description |
261
- | --------------------------- | ------ | --------------------------------------------------------- |
262
- | `POST /v1/chat/completions` | `POST` | Creates a model response for the given chat conversation. |
263
- | `GET /v1/models` | `GET` | Lists the currently available models. |
264
- | `POST /v1/embeddings` | `POST` | Creates an embedding vector representing the input text. |
265
-
266
- ### Anthropic Compatible Endpoints
267
-
268
- These endpoints are designed to be compatible with the Anthropic Messages API.
269
-
270
- | Endpoint | Method | Description |
271
- | -------------------------------- | ------ | ------------------------------------------------------------ |
272
- | `POST /v1/messages` | `POST` | Creates a model response for a given conversation. |
273
- | `POST /v1/messages/count_tokens` | `POST` | Calculates the number of tokens for a given set of messages. |
274
-
275
- ### Usage Monitoring Endpoints
276
-
277
- New endpoints for monitoring your Copilot usage and quotas.
278
-
279
- | Endpoint | Method | Description |
280
- | ------------ | ------ | ------------------------------------------------------------ |
281
- | `GET /usage` | `GET` | Get detailed Copilot usage statistics and quota information. |
282
- | `GET /token` | `GET` | Get the current Copilot token being used by the API. |
283
-
284
- ## Example Usage
285
-
286
- Using with npx:
181
+ ## Running from Source
287
182
 
288
183
  ```sh
289
- # Basic usage with start command
290
- npx xc-copilot-api@latest start
291
-
292
- # Run on custom port with verbose logging
293
- npx xc-copilot-api@latest start --port 8080 --verbose
294
-
295
- # Use with a business plan GitHub account
296
- npx xc-copilot-api@latest start --account-type business
297
-
298
- # Use with an enterprise plan GitHub account
299
- npx xc-copilot-api@latest start --account-type enterprise
300
-
301
- # Enable manual approval for each request
302
- npx xc-copilot-api@latest start --manual
303
-
304
- # Set rate limit to 30 seconds between requests
305
- npx xc-copilot-api@latest start --rate-limit 30
306
-
307
- # Wait instead of error when rate limit is hit
308
- npx xc-copilot-api@latest start --rate-limit 30 --wait
309
-
310
- # Provide GitHub token directly
311
- npx xc-copilot-api@latest start --github-token ghp_YOUR_TOKEN_HERE
312
-
313
- # Run only the auth flow
314
- npx xc-copilot-api@latest auth
315
-
316
- # Run auth flow with verbose logging
317
- npx xc-copilot-api@latest auth --verbose
318
-
319
- # Show your Copilot usage/quota in the terminal (no server needed)
320
- npx xc-copilot-api@latest check-usage
321
-
322
- # Display debug information for troubleshooting
323
- npx xc-copilot-api@latest debug
324
-
325
- # Display debug information in JSON format
326
- npx xc-copilot-api@latest debug --json
327
-
328
- # Initialize proxy from environment variables (HTTP_PROXY, HTTPS_PROXY, etc.)
329
- npx xc-copilot-api@latest start --proxy-env
184
+ bun install # install dependencies
185
+ bun run dev # development mode
186
+ bun run start # production mode
330
187
  ```
331
188
 
332
- ## Using the Usage Viewer
333
-
334
- After starting the server, a URL to the Copilot Usage Dashboard will be displayed in your console. This dashboard is a web interface for monitoring your API usage.
335
-
336
- 1. Start the server. For example, using npx:
337
- ```sh
338
- npx xc-copilot-api@latest start
339
- ```
340
- 2. The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:
341
- `https://billxc.github.io/copilot-api?endpoint=http://localhost:4141/usage`
342
- - If you use the `start.bat` script on Windows, this page will open automatically.
189
+ Prerequisites: Bun >= 1.2.x, GitHub account with Copilot subscription.
343
190
 
344
- The dashboard provides a user-friendly interface to view your Copilot usage data:
345
-
346
- - **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via the URL query parameter. You can change this URL to point to any other compatible API endpoint.
347
- - **Fetch Data**: Click the "Fetch" button to load or refresh the usage data. The dashboard will automatically fetch data on load.
348
- - **Usage Quotas**: View a summary of your usage quotas for different services like Chat and Completions, displayed with progress bars for a quick overview.
349
- - **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.
350
- - **URL-based Configuration**: You can also specify the API endpoint directly in the URL using a query parameter. This is useful for bookmarks or sharing links. For example:
351
- `https://billxc.github.io/copilot-api?endpoint=http://your-api-server/usage`
191
+ ## Usage Tips
352
192
 
353
- ## Using with Claude Code
193
+ - Use `--rate-limit 30 --wait` to stay within Copilot's rate limits without client errors.
194
+ - Use `--account-type business` or `enterprise` if you have a business/enterprise Copilot plan. See [official docs](https://docs.github.com/en/enterprise-cloud@latest/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/managing-github-copilot-access-to-your-organizations-network#configuring-copilot-subscription-based-network-routing-for-your-enterprise-or-organization).
195
+ - Use `--manual` to approve each request individually for fine-grained control.
354
196
 
355
- This proxy can be used to power [Claude Code](https://docs.anthropic.com/en/claude-code).
197
+ <details>
198
+ <summary><h2>Using with Docker</h2></summary>
356
199
 
357
- The quickest way to get started:
200
+ ### Pre-built Image
358
201
 
359
202
  ```sh
360
- # Start the server
361
- npx xc-copilot-api@latest start
362
-
363
- # Configure Claude Code (writes to ~/.claude/settings.json)
364
- npx xc-copilot-api@latest config --claude
365
- ```
366
-
367
- This merges the required `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` into your existing settings without overwriting other configuration. A backup of your original config is saved as `settings.json.bak`.
368
-
369
- > **Note:** Copilot API natively understands Claude model names (e.g. `claude-sonnet-4.5`, `opus[1m]`), so you don't need to set `ANTHROPIC_MODEL` or other model environment variables — they just work.
370
-
371
- If you prefer manual configuration, add the following to your `~/.claude/settings.json`:
372
-
373
- ```json
374
- {
375
- "env": {
376
- "ANTHROPIC_BASE_URL": "http://localhost:4141",
377
- "ANTHROPIC_AUTH_TOKEN": "Powered by xc copilot"
378
- }
379
- }
203
+ docker pull ghcr.io/billxc/copilot-api:latest
204
+ mkdir -p ./copilot-data
205
+ docker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api ghcr.io/billxc/copilot-api:latest
380
206
  ```
381
207
 
382
- You can find more options here: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables)
208
+ Available tags: `latest`, `v*.*.*`, `master`, `<sha>`
383
209
 
384
- You can also read more about IDE integration here: [Add Claude Code to your IDE](https://docs.anthropic.com/en/docs/claude-code/ide-integrations)
385
-
386
- ## Using with Codex CLI
210
+ ### Build from Source
387
211
 
388
212
  ```sh
389
- # Start the server
390
- npx xc-copilot-api@latest start
391
-
392
- # Configure Codex CLI (writes to ~/.codex/config.toml)
393
- npx xc-copilot-api@latest config --codex
394
- ```
395
-
396
- A backup of your original config is saved as `config.toml.bak`.
397
-
398
- If you prefer manual configuration, add the following to your `~/.codex/config.toml`:
399
-
400
- ```toml
401
- model = "gpt-5.4"
402
- model_provider = "copilot-api"
403
-
404
- [model_providers.copilot-api]
405
- name = "copilot-api"
406
- base_url = "http://localhost:4141/v1"
407
- wire_api = "responses"
213
+ docker build -t copilot-api .
214
+ mkdir -p ./copilot-data
215
+ docker run -p 4141:4141 -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api
408
216
  ```
409
217
 
410
- ## Running from Source
411
-
412
- The project can be run from source in several ways:
413
-
414
- ### Development Mode
218
+ ### Environment Variables
415
219
 
416
220
  ```sh
417
- bun run dev
221
+ docker run -p 4141:4141 -e GH_TOKEN=your_token copilot-api
418
222
  ```
419
223
 
420
- ### Production Mode
224
+ ### Docker Compose
421
225
 
422
- ```sh
423
- bun run start
226
+ ```yaml
227
+ version: "3.8"
228
+ services:
229
+ copilot-api:
230
+ image: ghcr.io/billxc/copilot-api:latest
231
+ ports:
232
+ - "4141:4141"
233
+ environment:
234
+ - GH_TOKEN=your_github_token_here
235
+ volumes:
236
+ - ./copilot-data:/root/.local/share/copilot-api
237
+ restart: unless-stopped
424
238
  ```
425
239
 
426
- ## Usage Tips
240
+ > **Note:** Token data is persisted in `copilot-data` on your host, mapped to `/root/.local/share/copilot-api` inside the container.
241
+
242
+ </details>
427
243
 
428
- - To avoid hitting GitHub Copilot's rate limits, you can use the following flags:
429
- - `--manual`: Enables manual approval for each request, giving you full control over when requests are sent.
430
- - `--rate-limit <seconds>`: Enforces a minimum time interval between requests. For example, `xc-copilot-api start --rate-limit 30` will ensure there's at least a 30-second gap between requests.
431
- - `--wait`: Use this with `--rate-limit`. It makes the server wait for the cooldown period to end instead of rejecting the request with an error. This is useful for clients that don't automatically retry on rate limit errors.
432
- - If you have a GitHub business or enterprise plan account with Copilot, use the `--account-type` flag (e.g., `--account-type business`). See the [official documentation](https://docs.github.com/en/enterprise-cloud@latest/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/managing-github-copilot-access-to-your-organizations-network#configuring-copilot-subscription-based-network-routing-for-your-enterprise-or-organization) for more details.
244
+ <details>
245
+ <summary><h2>Update Log</h2></summary>
433
246
 
434
- ## Update Log
247
+ ### v1.2.3 — Claude Model Selection & Codex 5.5
435
248
 
436
- ### Native Passthrough for Responses API and Claude API
249
+ - **Claude model version selection**: New `--claude-model` (`-m`) option for `config --claude`. Choose between Opus 4.7 (default) and Opus 4.6.
250
+ - **Codex default model updated**: `config --codex` now defaults to `gpt-5.5`.
251
+ - **Filter unsupported tools in Responses API**: Automatically strips `image_generation` and other unsupported tool types before forwarding to upstream, preventing errors from Codex CLI.
252
+ - **Bun idle timeout fix**: Increased `idleTimeout` to 255s to prevent streaming responses from being cut off after 10 seconds.
253
+ - **README restructured**: Quick Start first, collapsible Docker/Update Log sections, consolidated command reference.
437
254
 
438
- The proxy now supports **native passthrough** for both the OpenAI Responses API (`/responses`) and the Anthropic Messages API (`/v1/messages`, `/v1/messages/count_tokens`) when targeting supported models.
255
+ ### v1.2.1 — easy-service & Config Command
439
256
 
440
- #### What changed
257
+ - **New `config` subcommand**: One-command setup for Claude Code (`config --claude`) and Codex CLI (`config --codex`).
258
+ - **Background service**: Replaced built-in daemon with [easy-service](https://github.com/billxc/easy-service) for cross-platform service management.
441
259
 
442
- - **Claude API passthrough**: When the request model starts with `claude`, the entire Anthropic Messages request is forwarded directly to the upstream Copilot endpoint without any local translation. The request body, headers (`anthropic-version`, `anthropic-beta`, etc.), and response are passed through as-is.
260
+ ### v1.1.x — Anthropic 1M Models
443
261
 
444
- - **Responses API passthrough**: When the request model starts with `gpt`, the OpenAI Responses API request is forwarded directly to the upstream `/responses` endpoint without transformation.
262
+ - **Anthropic 1M model support**: Enhanced beta header handling for `claude-opus-4.6-1m` and other 1M context models.
445
263
 
446
- - **Non-matching models fall back to local translation**: For non-Claude models hitting `/v1/messages`, the existing Anthropic-to-OpenAI translation layer is still used, converting Anthropic Messages format to OpenAI Chat Completions and translating responses back.
264
+ ### v1.0.x — Native Passthrough
447
265
 
448
- #### Why this matters
266
+ - **Native passthrough for Responses API and Claude API**: Claude models forward the entire Anthropic Messages request directly to upstream. GPT models forward Responses API requests without transformation.
267
+ - **Full protocol fidelity**: Tool use, streaming, thinking blocks, vision — all preserved without translation loss.
268
+ - **Fallback translation**: Non-Claude models hitting `/v1/messages` still use the Anthropic-to-OpenAI translation layer.
449
269
 
450
- - **Full protocol fidelity**: Native passthrough preserves all upstream features (tool use, streaming, thinking blocks, vision, etc.) without any translation loss.
451
- - **Simpler architecture**: The passthrough path is a thin wrapper — no body parsing, no model normalization, no feature detection. What goes in is what goes out.
452
- - **Better compatibility**: Claude Code and other Anthropic-native clients get the exact upstream behavior they expect, including proper `tool_use`/`tool_result` round trips, `count_tokens` support, and streaming.
270
+ </details>