Main

.gitignore

@@ -11,4 +11,13 @@ node_modules/
 .eslintcache
 
 # build output
-dist/
+dist/
+
+# runtime artifacts
+server.log
+server.pid
+.eket/
+.eket-*.log
+
+# docker data
+copilot-data/

CLAUDE.md

@@ -0,0 +1,80 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Development Commands
+
+```sh
+bun install          # Install dependencies
+bun run dev          # Run in dev mode with hot reload
+bun run build        # Build for production (tsdown)
+bun run start        # Run production build
+bun run lint         # Lint with eslint
+bun run lint:all     # Lint all files
+bun run typecheck    # Type check with tsc
+bun test             # Run all tests
+bun test tests/foo.test.ts  # Run single test file
+```
+
+Pre-commit hooks run `lint --fix` via lint-staged automatically.
+
+## Architecture Overview
+
+**Core Structure:**
+- `src/main.ts` - CLI entry point using `citty`, defines subcommands (start, auth, check-usage, debug)
+- `src/start.ts` - Main server startup logic, handles authentication flow
+- `src/server.ts` - Hono server with routes for OpenAI & Anthropic compatible APIs
+- `src/auth.ts` - GitHub OAuth device flow authentication
+
+**Request Flow:**
+1. CLI command parsed by citty → `start.ts` handles auth/token refresh
+2. Token stored in `~/.local/share/copilot-api/` via `src/lib/paths.ts`
+3. Server starts on port 4141 (default) with Hono
+4. Incoming requests translated from OpenAI/Anthropic format → GitHub Copilot API
+
+**Key Services:**
+- `src/services/github/*` - GitHub API calls (device code, access token, user, copilot token)
+- `src/services/copilot/*` - Copilot API calls (chat completions, embeddings, models)
+- `src/routes/*` - API route handlers with format translation
+
+**Libraries:**
+- `src/lib/*` - Rate limiting, manual approval, proxy, tokenizer, state management
+
+**Route Structure:**
+- `/v1/chat/completions` - OpenAI compatible (translates to Copilot API)
+- `/v1/messages` - Anthropic Messages API compatible
+- `/v1/models` - Lists available models
+- `/v1/embeddings` - OpenAI compatible embeddings
+- `/usage` - Copilot usage/quota monitoring
+- `/token` - Current Copilot token info
+
+## Code Style
+
+- **Imports:** ESNext modules, use `~/*` path alias for `src/*`
+- **Types:** Strict mode, explicit types, no `any`
+- **Naming:** `camelCase` variables/functions, `PascalCase` types/classes
+- **Error Handling:** Use custom error classes from `src/lib/error.ts`
+- **Testing:** Bun test runner, tests in `tests/*.test.ts`
+
+## Configuration Files
+
+- `tsconfig.json` - TypeScript config with path aliases (`~/*` → `src/*`)
+- `tsdown.config.ts` - Build configuration (ESM, es2022 target, Node platform)
+- `eslint.config.js` - Linting rules (@echristian/eslint-config)
+- `package.json` - Scripts, dependencies, lint-staged config
+
+## State & Data Management
+
+**Runtime State:** `src/lib/state.ts` - In-memory state object storing:
+- GitHub/Copilot tokens
+- Account type, models, VSCode version cache
+- Rate limiting config and request timestamps
+- Manual approval flag
+
+**Persistent Data:** Tokens stored in `~/.local/share/copilot-api/` (see `src/lib/paths.ts`)
+
+## Testing Patterns
+
+- Test files in `tests/*.test.ts`
+- Examples: `anthropic-request.test.ts`, `anthropic-response.test.ts`, `create-chat-completions.test.ts`
+- Tests focus on request/response translation between OpenAI/Anthropic formats and Copilot API

README.md

@@ -44,6 +44,83 @@ A reverse-engineered proxy for the GitHub Copilot API that exposes it as an Open
 
 https://github.com/user-attachments/assets/7654b383-669d-4eb9-b23c-06d7aefee8c5
 
+## Quick Start: Claude Code with Copilot
+
+最快上手方式——一键安装并启动 Claude Code：
+
+```bash
+# 1. 安装引导（检查依赖、认证、配置 shell、生成 launchd plist）
+./setup.sh
+
+# 2. 重载 shell 配置
+source ~/.zshrc   # 或 source ~/.bashrc
+
+# 3. 启动
+claude-copilot                # 默认 sonnet 模型
+claude-copilot -m opus        # opus-4.7，高推理 effort
+claude-copilot -m opus-med    # opus-4.7，中推理 effort（推荐日常使用）
+claude-copilot -m haiku       # haiku，省配额
+```
+
+### 模型档位说明
+
+`claude-copilot` 支持三层模型分工，Claude Code 会根据任务复杂度自动选择：
+
+| 环境变量 | 用途 | 默认配置 |
+|---------|------|---------|
+| `ANTHROPIC_DEFAULT_OPUS_MODEL` | 复杂任务：规划、架构决策、多步推理 | `claude-opus-4.7` |
+| `ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_SONNET_MODEL` | 常规任务：写代码、单测、调试 | `claude-sonnet-4.6` |
+| `ANTHROPIC_SMALL_FAST_MODEL` / `ANTHROPIC_DEFAULT_HAIKU_MODEL` | 轻量任务：工具调用、文件读写、背景任务 | `claude-haiku-4.5` |
+
+**`-m` 参数对应关系：**
+
+| 参数 | 主模型 | Effort | 适用场景 |
+|-----|-------|--------|---------|
+| `sonnet`（默认）| sonnet-4.6 | 无 | 日常编码，subagent 用 opus-4.7 |
+| `opus` / `opus47` / `opus-high` | opus-4.7 | `high` | 深度推理、复杂架构 |
+| `opus-med` / `opus47-med` | opus-4.7 | `medium` | 均衡，推荐大多数重任务 |
+| `opus46` | opus-4.6 | 无 | opus-4.6（无 effort 支持） |
+| `haiku` | haiku-4.5 | 无 | 省配额、快速验证 |
+
+> **Reasoning Effort 说明**：仅 `claude-opus-4.7` 支持 effort（`low/medium/high/xhigh/max`）。
+> `opus-4.6`、`sonnet`、`haiku` 设置 effort 无效，proxy 会自动丢弃。
+
+### 常用命令
+
+```bash
+claude-copilot --status       # 检查服务、认证、可用模型
+claude-copilot --usage        # 查看配额用量（premium interactions 等）
+claude-copilot --stop         # 停止服务
+claude-copilot --daemon       # 守护模式（自动重启，Ctrl+C 退出）
+claude-copilot --setup        # 详细环境检查向导
+claude-copilot --port 4141    # 使用自定义端口
+```
+
+### 环境变量配置
+
+可通过以下环境变量覆盖默认行为（在 shell 配置文件中设置）：
+
+```bash
+export COPILOT_PORT=1234                  # 服务端口
+export COPILOT_SCRIPT_DIR=/path/to/repo   # copilot-api 源码目录
+export COPILOT_TIMEOUT_MS=3000000         # API 超时（毫秒）
+export COPILOT_AUTH_FILE=~/.local/share/copilot-api/github_token  # token 路径
+```
+
+### Shell 集成
+
+`claude-copilot.sh` 是一个可 source 的 shell 函数文件，支持 zsh / bash：
+
+```bash
+# 手动添加到 ~/.zshrc 或 ~/.bashrc
+export COPILOT_SCRIPT_DIR="/path/to/copilot-api"
+source "$COPILOT_SCRIPT_DIR/claude-copilot.sh"
+```
+
+或直接运行 `./setup.sh` 自动完成配置。
+
+---
+
 ## Prerequisites
 
 - Bun (>= 1.2.x)