codex-claude-proxy 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# Codex Claude Proxy
+
+![Architecture banner](./images/f757093f-507b-4453-994e-f8275f8b07a9.png)
+
+A local proxy server that exposes an **Anthropic-compatible API** (Claude Messages) backed by the **ChatGPT Codex backend**.
+
+It is designed primarily for **Claude Code CLI** (Anthropic-format client) while actually executing requests against Codex.
+
+> This project is inspired by the structure of the Antigravity Claude Proxy README in `antigravity-claude-proxy-main/README.md`, but this proxy targets **ChatGPT Codex** and does **not** implement all Antigravity features.
+
+---
+
+## Disclaimer (read before use)
+
+- **Not affiliated with OpenAI or Anthropic.** This is an independent open-source project and is not endorsed by, sponsored by, or affiliated with OpenAI or Anthropic.
+- “ChatGPT”, “OpenAI”, and “Codex” are trademarks of their respective owners.
+- “Claude” and “Anthropic” are trademarks of Anthropic PBC.
+- Software is provided **“as is”**, without warranty. You are responsible for complying with all applicable Terms of Service and Acceptable Use Policies.
+
+### Legal
+
+- **Not affiliated with OpenAI or Anthropic.** This is an independent open-source project and is not endorsed by, sponsored by, or affiliated with OpenAI or Anthropic.
+- “ChatGPT”, “OpenAI”, and “Codex” are trademarks of their respective owners.
+- “Claude” and “Anthropic” are trademarks of Anthropic PBC.
+- Software is provided "as is", without warranty. You are responsible for complying with all applicable Terms of Service and Acceptable Use Policies.
+
+---
+
+## How it works
+
+```
+┌──────────────────┐     ┌─────────────────────┐     ┌────────────────────────────┐
+│   Claude Code    │────▶│  This Proxy Server  │────▶│  ChatGPT Codex Backend API  │
+│ (Anthropic API)  │     │ (Anthropic ⇄ OpenAI)│     │ (codex/responses)           │
+└──────────────────┘     └─────────────────────┘     └────────────────────────────┘
+```
+
+At a high level:
+
+1. Claude Code calls this proxy using **Anthropic Messages API** endpoints (e.g. `/v1/messages`).
+2. The proxy maps the incoming “Claude model name” into a Codex model.
+3. The proxy converts formats as needed and returns responses back in Anthropic-compatible shapes, including streaming and tool calls.
+
+---
+
+## Model mapping (Claude name → Codex)
+
+This proxy accepts Claude-style model IDs (what Claude Code expects) and maps them to Codex-backed models.
+
+| Claude Code model (input) | Codex model used | Auth required | Notes |
+|---|---|---:|---|
+| `claude-sonnet-4-5` | **GPT-5.2 Codex** | Yes | Default “Sonnet” lane |
+| `claude-opus-4-5` | **GPT-5.3 Codex** | Yes | Default “Opus” lane |
+| `claude-haiku-4` | **GPT-5.2** (fast lane) | Yes | Lightweight / fast |
+
+---
+
+## Features
+
+- **Anthropic-compatible** API surface (works with Claude Code)
+- **OpenAI-compatible** endpoint (`/v1/chat/completions`) for quick testing and compatibility
+- **Streaming (SSE)** for both Messages and logs
+- **Native tool calling support** (proxy converts tool calls between formats)
+- **Multi-account ChatGPT OAuth** (switch accounts, refresh tokens, import from Codex)
+- **Web Dashboard** at `/`:
+  - manage accounts
+  - view quota snapshots
+  - quick test prompts
+  - live logs stream
+  - model mapping (Claude names → Codex models)
+
+---
+
+## Requirements
+
+- Node.js **18+**
+- A ChatGPT account authorized via OAuth
+
+---
+
+## Quick start
+
+```bash
+npm install
+npm start
+
+# WebUI
+open http://localhost:8081
+
+# Health
+curl http://localhost:8081/health
+```
+
+Default ports:
+
+| Port | Purpose |
+|---:|---|
+| `8081` | main server (API + WebUI) |
+| `1455` | OAuth callback (temporary) |
+
+---
+
+## Authenticate (Codex / ChatGPT)
+
+Codex-backed routes require at least one authenticated ChatGPT account.
+
+### Option A: Web Dashboard (recommended)
+
+1. Start the server
+2. Open `http://localhost:8081`
+3. Go to Accounts and add an account via OAuth (or use the Manual mode for headless environments)
+
+### Option B: CLI helpers
+
+Desktop (opens browser):
+
+```bash
+npm run accounts:add
+```
+
+Headless / VM:
+
+```bash
+npm run accounts:add:headless
+# Prints URL, you paste callback URL/code
+```
+
+### Option C: Import from Codex app
+
+```bash
+curl -X POST http://localhost:8081/accounts/import
+# Imports from ~/.codex/auth.json
+```
+
+Details: `docs/OAUTH.md` and `docs/ACCOUNTS.md`.
+
+---
+
+## Configure Claude Code to use the proxy
+
+### Automatic (recommended)
+
+```bash
+curl -X POST http://localhost:8081/claude/config/proxy
+```
+
+This updates `~/.claude/settings.json` to point Claude Code at `http://localhost:8081`.
+
+### Manual (env vars)
+
+```bash
+export ANTHROPIC_BASE_URL=http://localhost:8081
+export ANTHROPIC_API_KEY=any-key
+claude
+```
+
+More details: `docs/CLAUDE_INTEGRATION.md`.
+
+---
+
+## API surface (high level)
+
+- Anthropic-compatible:
+  - `POST /v1/messages`
+  - `GET  /v1/models`
+  - `POST /v1/messages/count_tokens`
+
+- OpenAI-compatible:
+  - `POST /v1/chat/completions`
+
+- Accounts:
+  - `GET  /accounts`
+  - `POST /accounts/add`
+  - `POST /accounts/add/manual`
+  - `POST /accounts/switch`
+  - `POST /accounts/refresh`, `POST /accounts/refresh/all`
+
+- Logs:
+  - `GET /api/logs`
+  - `GET /api/logs/stream?history=true`
+
+Full reference: `docs/API.md`.
+
+---
+
+## Documentation
+
+- `docs/ARCHITECTURE.md` — system overview and data flow
+- `docs/API.md` — endpoints, formats, streaming
+- `docs/OAUTH.md` — OAuth PKCE implementation + headless flow
+- `docs/ACCOUNTS.md` — multi-account storage, switching, refresh, quota caching
+- `docs/CLAUDE_INTEGRATION.md` — how to use with Claude Code
+- `docs/OPENCLAW.md` — using the proxy behind OpenClaw
+
+---
+
+## Notes / limitations
+
+- This project is intended for **local** or **trusted** environments.
+- Some behavior differs from Antigravity proxy; this repo focuses on ChatGPT Codex routing.
+
+---
+
+## License
+
+MIT

package/docs/ACCOUNTS.md

@@ -0,0 +1,202 @@
+# Account Management
+
+## Storage Structure
+
+### Main Registry
+
+**Location:** `~/.codex-claude-proxy/accounts.json`
+
+```json
+{
+  "accounts": [
+    {
+      "email": "user@gmail.com",
+      "accountId": "d41e9636-16d8-42be-91da-7ea8773bfb7e",
+      "planType": "plus",
+      "accessToken": "eyJhbGciOiJSUzI1NiIs...",
+      "refreshToken": "rt_WpTMn1...",
+      "idToken": "eyJhbGciOiJSUzI1NiIs...",
+      "expiresAt": 1770886178000,
+      "addedAt": "2026-02-13T04:00:00.000Z",
+      "lastUsed": "2026-02-13T04:30:00.000Z",
+      "quota": {
+        "usage": {...},
+        "account": {...},
+        "lastChecked": "2026-02-14T10:00:00.000Z"
+      }
+    }
+  ],
+  "activeAccount": "user@gmail.com",
+  "version": 1
+}
+```
+
+### Per-Account Tokens
+
+**Location:** `~/.codex-claude-proxy/accounts/<email>/auth.json`
+
+```json
+{
+  "auth_mode": "chatgpt",
+  "OPENAI_API_KEY": null,
+  "tokens": {
+    "id_token": "...",
+    "access_token": "...",
+    "refresh_token": "...",
+    "account_id": "..."
+  },
+  "last_refresh": "2026-02-14T10:00:00.000Z"
+}
+```
+
+## Operations
+
+### Add Account (OAuth)
+
+```bash
+curl -X POST http://localhost:8081/accounts/add
+
+# Returns OAuth URL to open in browser
+```
+
+### Import from Codex App
+
+```bash
+curl -X POST http://localhost:8081/accounts/import
+
+# Imports from ~/.codex/auth.json
+```
+
+### List Accounts
+
+```bash
+curl http://localhost:8081/accounts
+
+# Response
+{
+  "accounts": [
+    {
+      "email": "user@gmail.com",
+      "accountId": "...",
+      "planType": "plus",
+      "addedAt": "...",
+      "lastUsed": "...",
+      "isActive": true,
+      "tokenExpired": false,
+      "quota": {...}
+    }
+  ],
+  "activeAccount": "user@gmail.com",
+  "total": 1
+}
+```
+
+### Switch Active Account
+
+```bash
+curl -X POST http://localhost:8081/accounts/switch \
+  -H "Content-Type: application/json" \
+  -d '{"email":"other@gmail.com"}'
+```
+
+Switching:
+1. Updates `activeAccount` in `accounts.json`
+2. Updates auth file for the account
+3. Next API calls use new account's credentials
+
+### Remove Account
+
+```bash
+curl -X DELETE http://localhost:8081/accounts/user@gmail.com
+```
+
+Removes:
+- Account from registry
+- Per-account token directory
+
+### Refresh Tokens
+
+```bash
+# Active account
+curl -X POST http://localhost:8081/accounts/refresh
+
+# Specific account
+curl -X POST http://localhost:8081/accounts/user@gmail.com/refresh
+
+# All accounts
+curl -X POST http://localhost:8081/accounts/refresh/all
+```
+
+## Token Lifecycle
+
+### Expiration
+
+- Access tokens expire in ~1 hour (3600 seconds)
+- Refresh tokens are long-lived (weeks/months)
+
+### Auto-Refresh
+
+- Background refresh every **55 minutes**
+- Startup refresh 2 seconds after server start
+- Proactive refresh 5 minutes before expiry
+
+### Token Validation
+
+Before each API call:
+1. Check if token is expired or expiring within 5 minutes
+2. If yes, refresh using refresh token
+3. Use new access token for the call
+
+## Quota Tracking
+
+### Fetch Quota
+
+```bash
+curl http://localhost:8081/accounts/quota
+
+# Response
+{
+  "success": true,
+  "email": "user@gmail.com",
+  "quota": {
+    "usage": {
+      "totalTokenUsage": 15,
+      "limit": 100,
+      "remaining": 85,
+      "percentage": 15,
+      "resetAt": "..."
+    },
+    "account": {...}
+  },
+  "cached": false
+}
+```
+
+### Web UI Quota Display Rules
+
+- The Accounts table displays **remaining quota** as a percentage.
+- Remaining percentage is normalized to `0-100` to avoid broken UI values.
+- If `limitReached=true` or `allowed=false`, UI shows quota as exhausted even when percentage data is missing.
+- If usage data is unavailable, UI shows `-` instead of rendering a broken bar.
+- Reset window is shown using `usage.resetAt` (with fallback to `usage.raw.rate_limit.primary_window.reset_at`).
+- UI also shows a relative countdown (e.g. `Resets in 6d 13h`) when reset data is available.
+
+### Refresh All Quotas
+
+```bash
+curl http://localhost:8081/accounts/quota/all
+```
+
+## Account Persistence
+
+On server startup:
+1. `ensureAccountsPersist()` loads accounts
+2. Restores active account's auth
+3. Starts auto-refresh timer
+
+## Security
+
+- Tokens stored locally in `~/.codex-claude-proxy/`
+- Directory permissions: user read/write only
+- Never logged or exposed in API responses
+- Per-account isolation via separate directories

package/docs/API.md

@@ -0,0 +1,274 @@
+# API Reference
+
+## Main Endpoints
+
+### Haiku Routing Settings
+
+```bash
+GET /settings/haiku-model
+
+# Response
+{
+  "success": true,
+  "haikuKiloModel": "glm-5"
+}
+```
+
+```bash
+POST /settings/haiku-model
+Content-Type: application/json
+
+{
+  "haikuKiloModel": "minimax-2.5"
+}
+
+# Response
+{
+  "success": true,
+  "haikuKiloModel": "minimax-2.5"
+}
+```
+
+`claude-haiku-4` requests are routed according to this server-wide setting.
+
+### Chat Completions (OpenAI-compatible)
+
+```bash
+POST /v1/chat/completions
+Content-Type: application/json
+
+{
+  "model": "gpt-5.2",
+  "messages": [{"role": "user", "content": "Hello"}],
+  "tools": [...],
+  "stream": true
+}
+```
+
+### Messages (Anthropic-compatible)
+
+```bash
+POST /v1/messages
+Content-Type: application/json
+
+{
+  "model": "claude-sonnet-4-5",
+  "max_tokens": 1024,
+  "system": "You are helpful.",
+  "messages": [{"role": "user", "content": "Hello"}],
+  "tools": [...],
+  "stream": true
+}
+```
+
+### Models
+
+```bash
+GET /v1/models
+```
+
+### Token Counting
+
+```bash
+POST /v1/messages/count_tokens
+Content-Type: application/json
+
+{
+  "messages": [...],
+  "tools": [...]
+}
+```
+
+## Account Management
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/accounts` | GET | List all accounts |
+| `/accounts/status` | GET | Get account status summary |
+| `/accounts/add` | POST | Start OAuth flow (returns URL) |
+| `/accounts/switch` | POST | Switch active account |
+| `/accounts/:email` | DELETE | Remove account |
+| `/accounts/refresh` | POST | Refresh active account token |
+| `/accounts/refresh/all` | POST | Refresh all tokens |
+| `/accounts/:email/refresh` | POST | Refresh specific account |
+| `/accounts/import` | POST | Import from `~/.codex/auth.json` |
+| `/accounts/models` | GET | Get models for account |
+| `/accounts/quota` | GET | Get quota info |
+| `/accounts/quota/all` | GET | Refresh all quotas |
+| `/accounts/usage` | GET | Get usage stats |
+
+### Add Account
+
+```bash
+POST /accounts/add
+Content-Type: application/json
+
+# Optional: specify callback port
+{"port": 1455}
+
+# Response
+{
+  "status": "oauth_url",
+  "oauth_url": "https://auth.openai.com/oauth/authorize?...",
+  "state": "...",
+  "callback_port": 1455
+}
+```
+
+### Switch Account
+
+```bash
+POST /accounts/switch
+Content-Type: application/json
+
+{"email": "user@gmail.com"}
+
+# Response
+{"success": true, "message": "Switched to account: user@gmail.com"}
+```
+
+### OAuth Callback
+
+```bash
+GET /auth/callback?code=...&state=...
+```
+
+## Claude CLI Configuration
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/claude/config` | GET | View current config |
+| `/claude/config/proxy` | POST | Configure for proxy |
+| `/claude/config/direct` | POST | Configure for direct API |
+
+### Configure Proxy Mode
+
+```bash
+POST /claude/config/proxy
+
+# Response
+{
+  "success": true,
+  "message": "Claude CLI configured to use proxy at http://localhost:8081",
+  "config": {...}
+}
+```
+
+## Health
+
+```bash
+GET /health
+
+# Response
+{
+  "status": "ok",
+  "total": 2,
+  "active": "user@gmail.com",
+  "accounts": [...]
+}
+```
+
+## Error Responses
+
+### Authentication Error
+
+```json
+{
+  "type": "error",
+  "error": {
+    "type": "authentication_error",
+    "message": "No active account with valid credentials"
+  }
+}
+```
+
+### Rate Limit Error
+
+```json
+{
+  "type": "error",
+  "error": {
+    "type": "rate_limit_error",
+    "message": "Rate limited: ..."
+  }
+}
+```
+
+## Streaming Events
+
+Anthropic SSE format:
+
+```
+event: message_start
+data: {"type":"message_start","message":{...}}
+
+event: content_block_start
+data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
+
+event: content_block_delta
+data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}
+
+event: content_block_stop
+data: {"type":"content_block_stop","index":0}
+
+event: message_delta
+data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{...}}
+
+event: message_stop
+data: {"type":"message_stop"}
+
+data: [DONE]
+```
+
+## Tool Calling
+
+### Request with Tools
+
+```json
+{
+  "model": "claude-sonnet-4-5",
+  "messages": [
+    {"role": "user", "content": "What's the weather in Tokyo?"}
+  ],
+  "tools": [{
+    "name": "get_weather",
+    "description": "Get weather for a location",
+    "input_schema": {
+      "type": "object",
+      "properties": {
+        "location": {"type": "string"}
+      },
+      "required": ["location"]
+    }
+  }]
+}
+```
+
+### Response with Tool Use
+
+```json
+{
+  "id": "msg_...",
+  "type": "message",
+  "role": "assistant",
+  "content": [{
+    "type": "tool_use",
+    "id": "toolu_...",
+    "name": "get_weather",
+    "input": {"location": "Tokyo"}
+  }],
+  "stop_reason": "tool_use"
+}
+```
+
+### Tool Result
+
+```json
+{
+  "messages": [
+    {"role": "user", "content": "What's the weather?"},
+    {"role": "assistant", "content": [{"type": "tool_use", "id": "toolu_123", "name": "get_weather", "input": {"location": "Tokyo"}}]},
+    {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "toolu_123", "content": "Sunny, 22°C"}]}
+  ]
+}
+```