codex-claude-proxy 1.0.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,133 @@
+# Architecture
+
+## Overview
+
+```
+┌──────────────────┐     ┌─────────────────────┐     ┌────────────────────────────┐
+│   Claude Code    │────▶│  This Proxy Server  │────▶│  ChatGPT Backend API        │
+│   (Anthropic     │     │  (Anthropic format)  │     │  (chatgpt.com/backend-api/  │
+│    API format)   │     │                      │     │   codex/responses)          │
+└──────────────────┘     └─────────────────────┘     └────────────────────────────┘
+                                   │
+                                   ▼
+                         ┌─────────────────────┐
+                         │  Account Manager    │
+                         │  (~/.codex-claude-  │
+                         │   proxy/accounts.json)
+                         └─────────────────────┘
+```
+
+## Key Discovery
+
+The endpoint `https://chatgpt.com/backend-api/codex/responses` bypasses Cloudflare protection when called with proper authentication headers.
+
+## Project Structure
+
+```
+codex-claude-proxy/
+├── package.json
+├── README.md
+├── docs/
+│   ├── ARCHITECTURE.md
+│   ├── API.md
+│   ├── OAUTH.md
+│   ├── ACCOUNTS.md
+│   └── CLAUDE_INTEGRATION.md
+├── public/
+│   ├── index.html
+│   ├── css/style.css
+│   └── js/app.js              # Alpine UI logic
+└── src/
+    ├── index.js              # Express server + routes
+    ├── oauth.js              # OAuth 2.0 with PKCE
+    ├── account-manager.js    # Multi-account storage
+    ├── format-converter.js   # Anthropic ↔ OpenAI format
+    ├── response-streamer.js  # SSE streaming
+    ├── direct-api.js         # ChatGPT API client
+    ├── kilo-api.js           # Alternate upstream client
+    ├── kilo-format-converter.js # Anthropic ↔ OpenAI Chat conversion
+    ├── kilo-streamer.js      # Streaming adapter
+    ├── model-api.js          # Models & quota
+    ├── server-settings.js    # Server-wide settings persistence
+    └── claude-config.js      # Claude CLI config
+```
+
+## Module Responsibilities
+
+| File | Purpose |
+|------|---------|
+| `index.js` | Entry point (starts server) |
+| `server.js` | Express server, routes, request handling |
+| `routes/api-routes.js` | API route registrations (mounted by server) |
+| `oauth.js` | OAuth 2.0 PKCE flow, token exchange |
+| `account-manager.js` | Account persistence, switching, token refresh |
+| `format-converter.js` | Convert between Anthropic and OpenAI Responses API formats |
+| `response-streamer.js` | Parse SSE events, convert to Anthropic streaming format |
+| `direct-api.js` | HTTP client for ChatGPT backend |
+| `kilo-api.js` | Alternate upstream client |
+| `kilo-format-converter.js` | Anthropic ↔ OpenAI Chat conversion |
+| `kilo-streamer.js` | Streaming adapter |
+| `server-settings.js` | Server-wide settings persistence |
+| `model-api.js` | Fetch models, usage, quota |
+| `claude-config.js` | Read/write `~/.claude/settings.json` |
+
+## Data Flow
+
+### Request Flow
+
+1. Claude Code sends Anthropic-format request to `/v1/messages`
+2. The proxy maps the requested model to an upstream target
+3. If the mapped path requires ChatGPT auth, the account manager loads/refreshes credentials
+4. Request is converted and sent upstream
+5. Response is streamed back as Anthropic SSE events
+
+### Web UI Account/Quota Flow
+
+1. Web UI loads account list from `/accounts`
+2. Web UI fetches quota snapshots from `/accounts/quota/all`
+3. Quota values are merged into account rows for table + modal views
+4. Remaining quota is rendered from normalized usage percentages
+5. On mobile/tablet, sidebar navigation auto-closes after tab change and account table uses horizontal scrolling
+
+### Format Conversion
+
+**Anthropic → OpenAI Responses API:**
+- `messages` → `input` array with `type: 'message'`
+- `system` → `instructions`
+- `tools` → OpenAI function format
+- `tool_use` → `function_call` input item
+- `tool_result` → `function_call_output` input item
+
+**OpenAI → Anthropic:**
+- `output_text` → `{ type: 'text', text: ... }`
+- `function_call` → `{ type: 'tool_use', id, name, input }`
+- SSE events converted to Anthropic streaming format
+
+## Available Models
+
+| Model | Description |
+|-------|-------------|
+| `gpt-5.3-codex` | Latest agentic coding model |
+| `gpt-5.2-codex` | Frontier agentic coding model |
+| `gpt-5.2` | General-purpose frontier model |
+
+## Model Mapping
+
+Claude model names are automatically mapped:
+
+| Claude Model | Codex Model |
+|--------------|-------------|
+| `claude-opus-4-5` | `gpt-5.3-codex` |
+| `claude-sonnet-4-5` | `gpt-5.2` |
+| `claude-haiku-4` | routed by server setting |
+
+Haiku routing is controlled by a server-wide setting (`/settings/haiku-model`).
+
+## Data Storage
+
+| Location | Contents |
+|----------|----------|
+| `~/.codex-claude-proxy/accounts.json` | Account registry, active account |
+| `~/.codex-claude-proxy/accounts/<email>/auth.json` | Per-account tokens |
+| `~/.claude/settings.json` | Claude CLI config (we update this) |
+| `~/.codex/auth.json` | Codex app auth (read for import) |

package/docs/CLAUDE_INTEGRATION.md

@@ -0,0 +1,163 @@
+# Claude Code Integration
+
+## Setup
+
+### Automatic Configuration
+
+```bash
+curl -X POST http://localhost:8081/claude/config/proxy
+```
+
+Updates `~/.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://localhost:8081",
+    "ANTHROPIC_API_KEY": "any-key",
+    "ANTHROPIC_MODEL": "claude-sonnet-4-5",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-5",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4"
+  }
+}
+```
+
+### Manual Configuration
+
+```bash
+export ANTHROPIC_BASE_URL=http://localhost:8081
+export ANTHROPIC_API_KEY=any-key
+claude
+```
+
+## Using Claude Code
+
+When prompted about API key:
+
+```
+Detected a custom API key in your environment
+ANTHROPIC_API_KEY: any-key
+Do you want to use this API key?
+❯ 1. Yes          <-- Choose this
+   2. No (recommended)
+```
+
+## How It Works
+
+### Request Flow
+
+```
+Claude Code (Anthropic format)
+         ↓
+    Proxy Server
+         ↓
+  Format Conversion
+         ↓
+ChatGPT Backend API
+         ↓
+   Response Stream
+         ↓
+  Format Conversion
+         ↓
+Claude Code (Anthropic format)
+```
+
+### Format Conversion
+
+**Anthropic → OpenAI Responses API:**
+
+```javascript
+// Anthropic request
+{
+  "model": "claude-sonnet-4-5",
+  "system": "You are helpful.",
+  "messages": [
+    {"role": "user", "content": "Hello"},
+    {"role": "assistant", "content": [{"type": "tool_use", "id": "t1", "name": "fn", "input": {}}]},
+    {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "t1", "content": "result"}]}
+  ],
+  "tools": [...]
+}
+
+// Converted to OpenAI Responses API
+{
+  "model": "gpt-5.2-codex",
+  "instructions": "You are helpful.",
+  "input": [
+    {"type": "message", "role": "user", "content": "Hello"},
+    {"type": "function_call", "id": "fc_t1", "call_id": "fc_t1", "name": "fn", "arguments": "{}"},
+    {"type": "function_call_output", "call_id": "fc_t1", "output": "result"}
+  ],
+  "tools": [...],
+  "store": false,
+  "stream": true
+}
+```
+
+**Key Conversions:**
+- `system` → `instructions`
+- `messages` → `input` array
+- `tool_use` → `function_call` + `function_call_output` items
+- Tool IDs prefixed with `fc_` for API compatibility
+
+### Streaming Events
+
+OpenAI Responses API → Anthropic SSE:
+
+| OpenAI Event | Anthropic Event |
+|--------------|-----------------|
+| `response.output_item.added` | `message_start`, `content_block_start` |
+| `response.output_text.delta` | `content_block_delta` (text_delta) |
+| `response.function_call_arguments.delta` | `content_block_delta` (input_json_delta) |
+| `response.completed` | `message_delta`, `message_stop` |
+
+## Tool Calling
+
+Works natively via OpenAI Responses API:
+
+1. Claude Code sends tools in Anthropic format
+2. Proxy converts to OpenAI function format
+3. ChatGPT executes and returns function calls
+4. Proxy converts back to Anthropic `tool_use` blocks
+5. Claude Code processes and returns tool results
+
+## View Configuration
+
+```bash
+curl http://localhost:8081/claude/config
+```
+
+## Revert to Direct API
+
+```bash
+curl -X POST http://localhost:8081/claude/config/direct \
+  -H "Content-Type: application/json" \
+  -d '{"apiKey":"sk-ant-..."}'
+```
+
+## Troubleshooting
+
+### Claude Code hangs
+
+1. Check proxy health: `curl http://localhost:8081/health`
+2. Verify config: `cat ~/.claude/settings.json`
+3. Re-configure: `curl -X POST http://localhost:8081/claude/config/proxy`
+
+### "No active account" error
+
+Add an account first:
+
+```bash
+curl -X POST http://localhost:8081/accounts/import
+# or use WebUI
+```
+
+### Tool calls not working
+
+Ensure you're using the direct API mode (not CLI subprocess). Check:
+
+```bash
+curl http://localhost:8081/health
+# Should show accounts with valid tokens
+```

package/docs/OAUTH.md

@@ -0,0 +1,201 @@
+# OAuth Implementation
+
+## Configuration
+
+```javascript
+OAUTH_CONFIG = {
+  clientId: 'app_EMoamEEZ73f0CkXaXp7hrann',
+  authUrl: 'https://auth.openai.com/oauth/authorize',
+  tokenUrl: 'https://auth.openai.com/oauth/token',
+  scopes: ['openid', 'profile', 'email', 'offline_access'],
+  callbackPort: 1455,
+  callbackPath: '/auth/callback'
+}
+```
+
+## Authorization Methods
+
+### Method A: WebUI (Recommended)
+
+1. Open `http://localhost:8081` in your browser
+2. Click **Add Account** → **Connect via OAuth**
+3. Complete authorization in the popup
+
+### Method B: WebUI Manual Mode (Headless)
+
+For servers without a browser:
+
+1. Click **Add Account** → **Manual Authorization**
+2. Copy the OAuth URL
+3. Open URL on another device (your local machine)
+4. Complete authorization
+5. Copy the callback URL or authorization code
+6. Paste back in the WebUI
+
+### Method C: CLI (Desktop)
+
+```bash
+npm run accounts:add
+# Opens browser for OAuth
+```
+
+### Method D: CLI Headless Mode
+
+```bash
+npm run accounts:add:headless
+# Prints URL, you paste the callback URL/code
+```
+
+### Method E: API (Headless)
+
+```bash
+# 1. Get OAuth URL and verifier
+curl -X POST http://localhost:8081/accounts/add
+
+# Response includes oauth_url, verifier, state
+
+# 2. Open URL on another device, complete auth
+
+# 3. Submit authorization code
+curl -X POST http://localhost:8081/accounts/add/manual \
+  -H "Content-Type: application/json" \
+  -d '{"code":"<code_or_callback_url>","verifier":"<verifier_from_step_1>"}'
+```
+
+## PKCE Flow
+
+### 1. Generate PKCE Challenge
+
+```javascript
+// Verifier: 32 random bytes, base64url encoded
+verifier = crypto.randomBytes(32).toString('base64url')
+
+// Challenge: SHA256 hash of verifier
+challenge = sha256(verifier).base64url
+```
+
+### 2. Authorization URL
+
+```
+https://auth.openai.com/oauth/authorize?
+  response_type=code
+  &client_id=app_EMoamEEZ73f0CkXaXp7hrann
+  &redirect_uri=http://localhost:1455/auth/callback
+  &scope=openid profile email offline_access
+  &code_challenge=<challenge>
+  &code_challenge_method=S256
+  &state=<random_state>
+  &prompt=login
+  &max_age=0
+```
+
+**Key parameters for multi-account:**
+- `prompt=login` - Forces login screen (ignores session cookies)
+- `max_age=0` - Forces re-authentication
+
+### 3. Token Exchange
+
+```javascript
+POST https://auth.openai.com/oauth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=authorization_code
+&code=<authorization_code>
+&redirect_uri=http://localhost:1455/auth/callback
+&client_id=app_EMoamEEZ73f0CkXaXp7hrann
+&code_verifier=<verifier>
+```
+
+### 4. Token Response
+
+```json
+{
+  "access_token": "eyJhbGciOiJSUzI1NiIs...",
+  "refresh_token": "rt_WpTMn1...",
+  "id_token": "eyJhbGciOiJSUzI1NiIs...",
+  "expires_in": 3600,
+  "token_type": "Bearer"
+}
+```
+
+## JWT Claims
+
+Decoded `access_token` payload:
+
+```json
+{
+  "https://api.openai.com/auth": {
+    "chatgpt_account_id": "d41e9636-...",
+    "chatgpt_plan_type": "plus",
+    "chatgpt_user_id": "user-..."
+  },
+  "https://api.openai.com/profile": {
+    "email": "user@gmail.com",
+    "email_verified": true
+  },
+  "exp": 1770886178
+}
+```
+
+## Token Refresh
+
+```javascript
+POST https://auth.openai.com/oauth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=refresh_token
+&refresh_token=<refresh_token>
+&client_id=app_EMoamEEZ73f0CkXaXp7hrann
+```
+
+## Auto-Refresh
+
+- Tokens auto-refresh every **55 minutes**
+- Proactive refresh before API calls if expiring within 5 minutes
+- Startup refresh 2 seconds after server start
+
+## Web Flow vs CLI Flow
+
+### Web Flow (WebUI)
+
+1. `POST /accounts/add` → returns OAuth URL
+2. Frontend opens popup with URL
+3. User authenticates in popup
+4. Browser redirects to callback
+5. Server handles callback, stores tokens
+6. Popup notifies parent via `postMessage`
+
+### CLI Flow
+
+1. `POST /accounts/add` → starts callback server on port 1455
+2. Server opens browser with OAuth URL
+3. User authenticates
+4. Browser redirects to callback
+5. Server exchanges code for tokens
+
+## Multi-Account Support
+
+The key to multi-account support is forcing a fresh login each time:
+
+1. `prompt=login` - Shows login screen even if already logged in
+2. `max_age=0` - Requires re-authentication
+3. Each account stored with unique email as identifier
+
+## Troubleshooting
+
+### OAuth returns existing account
+
+- Browser may have aggressive cookie caching
+- Try manual logout: https://auth.openai.com/logout
+- Clear browser cookies for auth.openai.com
+
+### Callback timeout
+
+- Default timeout: 2 minutes
+- Ensure port 1455 is available
+- Check firewall isn't blocking localhost
+
+### Token refresh fails
+
+- Refresh token may have expired
+- Re-add the account via WebUI