|
| 1 | +## CRITICAL: File Editing on Windows |
| 2 | +### ⚠️ MANDATORY: Always Use Backslashes on Windows for File Paths |
| 3 | +**When using Edit or MultiEdit tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`).** |
| 4 | +#### ❌ WRONG - Will cause errors: |
| 5 | +``` |
| 6 | +Edit(file_path: "D:/repos/project/file.tsx", ...) |
| 7 | +MultiEdit(file_path: "D:/repos/project/file.tsx", ...) |
| 8 | +``` |
| 9 | +#### ✅ CORRECT - Always works: |
| 10 | +``` |
| 11 | +Edit(file_path: "D:\repos\project\file.tsx", ...) |
| 12 | +MultiEdit(file_path: "D:\repos\project\file.tsx", ...) |
| 13 | +``` |
| 14 | + |
| 15 | +# CLAUDE.md |
| 16 | + |
| 17 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 18 | + |
| 19 | +## Development commands |
| 20 | + |
| 21 | +The project is a Bun/TypeScript server. Most common workflows use the `bun` CLI. |
| 22 | + |
| 23 | +```sh |
| 24 | +# install deps |
| 25 | +bun install |
| 26 | + |
| 27 | +# compile to `dist/` (used by the published package) |
| 28 | +bun run build # runs `tsdown` as defined in package.json |
| 29 | + |
| 30 | +# run in development mode with file watching |
| 31 | +bun run dev # equivalent to `bun run --watch ./src/main.ts` |
| 32 | + |
| 33 | +# run the production entrypoint from source |
| 34 | +bun run start # sets NODE_ENV=production and executes ./src/main.ts |
| 35 | + |
| 36 | +# linting |
| 37 | +bun run lint # eslint with cache |
| 38 | +bun run lint:all # lint entire repo |
| 39 | + |
| 40 | +# type check |
| 41 | +bun run typecheck # invokes tsc |
| 42 | + |
| 43 | +# tests |
| 44 | +env BUN_INSTALL && bun test # Bun’s test runner executes files in tests/**/*.ts |
| 45 | +``` |
| 46 | + |
| 47 | +There are a few other helper scripts (knip, release) used by the repo but the above are the ones you will use most often. |
| 48 | + |
| 49 | +### Docker |
| 50 | + |
| 51 | +The README already documents building (`docker build -t copilot-api .`) and running the container. A `start.bat` script is provided for Windows. The image exposes port `4141` and persists the GitHub token under `/root/.local/share/copilot-api` when a host volume is mounted. |
| 52 | + |
| 53 | +## High‑level architecture |
| 54 | + |
| 55 | +- **CLI entrypoint**: `src/main.ts` defines a `citty` command with four subcommands: `start`, `auth`, `check-usage`, and `debug`. Each command lives in its own module (`src/auth.ts`, `src/start.ts`, etc.) and exports a `defineCommand` object. |
| 56 | + |
| 57 | +- **State & helpers**: `src/lib/*` contains lightweight utilities and shared state: |
| 58 | + - `state.ts` is a simple singleton holding tokens, rate‑limit settings, cached models, etc. |
| 59 | + - `token.ts` and `auth.ts` manage GitHub/Copilot authentication flows. |
| 60 | + - `paths.ts` ensures the filesystem layout for storing tokens. |
| 61 | + - `proxy.ts`, `rate-limit.ts`, `utils.ts`, and other modules implement miscellaneous helpers used across commands and services. |
| 62 | + |
| 63 | +- **Server and routing**: `src/server.ts` builds a Hono application. The bulk of the HTTP API is defined under `src/routes/*`: |
| 64 | + - `chat-completions`, `embeddings`, and `models` expose OpenAI‑compatible endpoints. |
| 65 | + - `messages` implements Anthropic‑style `/v1/messages` and token counting. |
| 66 | + - `token.ts` and `usage.ts` provide usage‑monitoring endpoints used by the web dashboard. |
| 67 | + - Each route’s handler usually delegates to a corresponding service in `src/services/copilot`. |
| 68 | + |
| 69 | +- **Copilot services**: `src/services/copilot/*` contains the code that translates incoming requests to the reverse‑engineered GitHub Copilot API, adding proper headers, token rotation, and streaming support. There are helper services for creating chat completions, embeddings, fetching available models, etc. |
| 70 | + |
| 71 | +- **GitHub services**: `src/services/github/*` call GitHub’s OAuth/device‑flow endpoints to obtain a Copilot token, and fetch usage stats. |
| 72 | + |
| 73 | +- **Entrypoint logic**: `src/start.ts` wires everything together. It processes CLI flags (rate limits, manual approval, account type, `--claude-code` helper), initializes state, caches available models and VSCode version, optionally generates environment variables for launching Claude Code, and finally starts the HTTP server with `srvx`. |
| 74 | + |
| 75 | +- **Tests**: The `tests/` directory contains a handful of unit tests written against Bun’s test runner (`bun:test`). They mock `fetch` and exercise the service modules. |
| 76 | + |
| 77 | +- **Packaging**: `tsdown` compiles TypeScript to `dist/` which is published to npm; `package.json` declares the CLI binary as `./dist/main.js`. |
| 78 | + |
| 79 | +### Important notes for future instances |
| 80 | + |
| 81 | +- The project targets Bun and assumes ESM (`"type": "module"` in package.json). |
| 82 | +- Routes and services avoid complex dependency injection; state is read from the singleton and mutated directly. |
| 83 | +- Rate‑limit, manual approval, and other runtime flags are stored in `state` and consulted by middleware in the route handlers. |
| 84 | +- The codebase is intentionally small; most of the logic lives in a few dozen TypeScript files under `src/`. |
| 85 | + |
| 86 | +By referencing this file, future Claude Code sessions should quickly understand how to build, run, and navigate the repository. |
| 87 | + |
| 88 | +## Known runtime quirks |
| 89 | + |
| 90 | +* When using GPT‑5 mini (or other unsupported model names) with Claude Code through the proxy, the GitHub Copilot backend may respond with a 400 `model_not_supported` error even though the request may still complete successfully. Example log output: |
| 91 | + |
| 92 | + ``` |
| 93 | + ERROR Failed to create chat completions Response { status: 400, |
| 94 | + statusText: 'Bad Request', |
| 95 | + ... |
| 96 | + url: 'https://api.githubcopilot.com/chat/completions' } |
| 97 | +
|
| 98 | + ERROR Error occurred: Failed to create chat completions |
| 99 | +
|
| 100 | + at createChatCompletions (.../dist/main.js:783:9) |
| 101 | + … |
| 102 | +
|
| 103 | + ERROR HTTP error: { error: { message: 'The requested model is not supported.', |
| 104 | + code: 'model_not_supported', |
| 105 | + param: 'model', |
| 106 | + type: 'invalid_request_error' } } |
| 107 | + ``` |
| 108 | + |
| 109 | + The underlying API still returns a response and Claude Code continues to work. There are no open pull requests currently addressing this; the only active PR (`coderabbitai/docstrings/0ea08fe`) adds API key authentication and docstrings, which is unrelated. Future changes may need to add model name validation or mapping if GitHub starts rejecting these names more strictly. |
0 commit comments