claude-codex-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,227 @@
+# Codex Claude Proxy
+
+![Architecture banner](./images/f757093f-507b-4453-994e-f8275f8b07a9.png)
+
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)
+[![Node.js Version](https://img.shields.io/badge/Node.js-18%2B-blue.svg)](https://nodejs.org/)
+[![GitHub stars](https://img.shields.io/github/stars/zzy-life/codex-claude-proxy?style=social)](https://github.com/zzy-life/codex-claude-proxy)
+
+> **Use Claude Code CLI with the power of ChatGPT Codex models.**
+> A local proxy that translates Anthropic API requests into ChatGPT Codex calls, enabling you to use the `claude` CLI tool with your ChatGPT Free/Plus/Pro subscription.
+
+---
+
+## 🚀 Features
+
+- **Seamless Translation**: Translates Anthropic Messages API calls to ChatGPT Codex format.
+- **Model Mapping**: automatically maps `claude-sonnet` and `claude-opus` to their Codex equivalents.
+- **Multi-Account Support**: Manage multiple ChatGPT accounts with easy switching and auto-refresh.
+- **Web Dashboard**: Built-in UI (`http://localhost:8081`) for managing accounts, viewing logs, and testing prompts.
+- **Raw Proxy Payload Logs**: Optional debug logging for Claude Code requests, upstream Codex payloads, completed responses, and upstream errors.
+- **Streaming Support**: Full Server-Sent Events (SSE) support for real-time responses.
+- **Native Tool Calling**: Supports Claude's tool use capabilities by translating them to Codex function calls.
+
+---
+
+## � Security & Privacy
+
+**Is this a malicious proxy? No.**
+
+- **Local Execution**: This server runs entirely on your local machine (`localhost`).
+- **Direct Communication**: It connects *directly* to OpenAI/ChatGPT endpoints. No data is sent to any third-party server.
+- **Open Source**: The full source code is available here for you to audit.
+- **No Data Collection**: We do not track your prompts, keys, or personal data.
+
+---
+
+## ⚙️ How it works
+
+This tool acts as a "translation layer" between the Claude CLI and ChatGPT's Codex backend.
+
+1.  **Intercept**: Claude Code CLI sends a request to `localhost:8081` (thinking it's Anthropic's API).
+2.  **Translate**: The proxy converts the Anthropic-format JSON into the specific payload format required by ChatGPT's internal Codex API.
+3.  **Forward**: The request is sent securely to ChatGPT using your own authenticated session.
+4.  **Stream**: The response from ChatGPT is converted back into Anthropic's Server-Sent Events (SSE) format and streamed to your terminal.
+
+```
+┌──────────────────┐     ┌─────────────────────┐     ┌────────────────────────────┐
+│   Claude Code    │────▶│  This Proxy Server  │────▶│  ChatGPT Codex Backend API  │
+│ (Anthropic API)  │     │ (Anthropic ⇄ OpenAI)│     │ (codex/responses)           │
+└──────────────────┘     └─────────────────────┘     └────────────────────────────┘
+```
+
+---
+
+## �📦 Installation
+
+You don't need to install anything if you just want to run it:
+
+```bash
+# Run directly with npx
+npx claude-codex-proxy@latest start
+```
+
+Or install globally to use the CLI commands anywhere:
+
+```bash
+npm install -g claude-codex-proxy
+claude-codex-proxy start
+```
+
+---
+
+## 🚦 Quick Start
+
+### 1. Start the Proxy
+
+```bash
+npx claude-codex-proxy@latest start
+```
+The server will start at `http://localhost:8081`.
+
+### 2. Add Your Account
+
+#### **Option A: Web Dashboard (Local Desktop)**
+
+1. Open the dashboard at **[http://localhost:8081](http://localhost:8081)**
+2. Go to the **Accounts** tab
+3. Click **Add Account** and login with your ChatGPT account
+
+#### **Option B: CLI (Desktop or Headless/VM)**
+
+```bash
+# Desktop (opens browser)
+claude-codex-proxy accounts add
+
+# Headless/VM server (manual code input)
+claude-codex-proxy accounts add --no-browser
+```
+
+For **headless/VM servers** without a browser:
+1. Run the command with `--no-browser`
+2. It will print a URL - copy and open it on a device with a browser
+3. Complete login on that device
+4. After redirect, copy the callback URL (or just the code)
+5. Paste it back in the terminal
+
+### 3. Configure Claude Code
+   Run this command to automatically configure your `claude` CLI to use the proxy:
+   ```bash
+   curl -X POST http://localhost:8081/claude/config/proxy
+   ```
+
+   *Alternatively, set the environment variables manually:*
+   ```bash
+   export ANTHROPIC_BASE_URL=http://localhost:8081
+   export ANTHROPIC_API_KEY=dummy-key # The key is ignored but required by the CLI
+   ```
+
+   To skip Claude Code's login/onboarding prompt, edit `~/.claude.json` and add:
+   ```json
+   {
+     "hasCompletedOnboarding": true
+   }
+   ```
+
+4. **Run Claude**:
+   ```bash
+   claude
+   ```
+
+---
+
+## 🧠 Model Mapping
+
+The proxy resolves model names dynamically, so Claude Code can request Claude-style names while the proxy routes them to Codex models through your ChatGPT account.
+
+Default mapping:
+
+| Requested Model | Upstream Model | Auth Required | Description |
+| :--- | :--- | :---: | :--- |
+| `claude-*sonnet*` | `gpt-5.5` | ✅ | Uses the configured Sonnet-family Codex model. |
+| `claude-*opus*` | `gpt-5.5` | ✅ | Uses the configured Opus-family Codex model. |
+| `claude-*haiku*` | `gpt-5.4-mini` | ✅ | Uses the configured Haiku-family Codex model by default. |
+| `gpt-*` | unchanged | ✅ | Direct Codex model IDs pass through without remapping. |
+| unknown model | `gpt-5.5` | ✅ | Falls back to the configured default Codex model. |
+
+You can customize mappings from the Web Dashboard, go to the model settings, and choose the Codex model used for each Claude family.
+
+---
+
+## 🛠️ Configuration & API
+
+### Web Dashboard
+Visit `http://localhost:8081` to:
+- **Manage Accounts**: Add, remove, or switch active ChatGPT accounts.
+- **View Logs**: See real-time request/response logs for debugging.
+- **Test Models**: Run quick tests against the configured models.
+- **Configure Raw Proxy Payload Logs**: Enable detailed debugging logs from the Settings tab when you need to inspect raw Claude Code requests and upstream Codex payloads.
+
+### Raw Proxy Payload Logs
+Raw payload logging is disabled by default because it may include prompts, tool results, file contents, and upstream response bodies. When enabled, the Logs tab captures:
+
+- `[Claude Request]`: the original Anthropic-compatible request body received from Claude Code.
+- `[Client Request]`: the original OpenAI Chat Completions-compatible request body, when using `/v1/chat/completions`.
+- `[OpenAI Request]`: the converted payload sent to the ChatGPT Codex Responses API.
+- `[OpenAI Response Completed]`: the completed upstream response object.
+- `[OpenAI Error]`: non-2xx upstream status and error body.
+
+You can enable it from the Web Dashboard under **Settings → Raw Proxy Payload Logs**, or via API:
+
+```bash
+curl -X POST http://localhost:8081/settings/raw-proxy-logs \
+  -H "Content-Type: application/json" \
+  -d '{"enabled":true}'
+```
+
+Disable it again with:
+
+```bash
+curl -X POST http://localhost:8081/settings/raw-proxy-logs \
+  -H "Content-Type: application/json" \
+  -d '{"enabled":false}'
+```
+
+Check the current state:
+
+```bash
+curl http://localhost:8081/settings/raw-proxy-logs
+```
+
+Authentication headers and access tokens are not logged.
+
+### API Endpoints
+- `GET /health`: Check server status.
+- `GET /accounts`: List configured accounts.
+- `POST /v1/messages`: Anthropic-compatible chat completion endpoint.
+
+See [API Documentation](./docs/API.md) for full details.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+---
+
+## 📄 License
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## ⚠️ Disclaimer
+This project is an independent open-source tool and is not affiliated with, endorsed by, or sponsored by Anthropic or OpenAI. "Claude" is a trademark of Anthropic PBC. "ChatGPT" and "Codex" are trademarks of OpenAI. Use responsibly and in accordance with applicable Terms of Service.
+
+---
+
+<div align="center">
+  <p>If you find this project useful, please give it a star! ⭐️</p>
+  <a href="https://github.com/zzy-life/codex-claude-proxy">
+    <img src="https://img.shields.io/github/stars/zzy-life/codex-claude-proxy?style=social" alt="Star on GitHub">
+  </a>
+</div>

package/bin/cli.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { readFileSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const packageJson = JSON.parse(
+  readFileSync(join(__dirname, '..', 'package.json'), 'utf-8')
+);
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function showHelp() {
+  console.log(`
+codex-claude-proxy v${packageJson.version}
+
+Proxy server for using ChatGPT Codex models with Claude Code CLI.
+
+USAGE:
+  codex-claude-proxy <command> [options]
+
+COMMANDS:
+  start                 Start the proxy server (default port: 8081)
+  accounts              Manage ChatGPT accounts (interactive)
+  accounts add          Add a new ChatGPT account via OAuth
+  accounts add --no-browser  Add account manually (headless/VM)
+  accounts list         List all configured accounts
+  accounts remove       Remove accounts interactively
+  accounts verify       Verify account tokens are valid
+  accounts clear        Remove all accounts
+
+OPTIONS:
+  --help, -h            Show this help message
+  --version, -v         Show version number
+
+ENVIRONMENT:
+  PORT                  Server port (default: 8081)
+
+EXAMPLES:
+  codex-claude-proxy start
+  PORT=3000 codex-claude-proxy start
+  codex-claude-proxy accounts add
+  codex-claude-proxy accounts add --no-browser
+  codex-claude-proxy accounts list
+  codex-claude-proxy accounts verify
+
+HEADLESS/VM USAGE:
+  1. Run: codex-claude-proxy accounts add --no-browser
+  2. Copy the URL shown and open in browser on another device
+  3. After login, paste the callback URL back in terminal
+
+CONFIGURATION:
+  Claude Code CLI (~/.claude/settings.json):
+    {
+      "env": {
+        "ANTHROPIC_BASE_URL": "http://localhost:8081",
+        "ANTHROPIC_API_KEY": "dummy"
+      }
+    }
+`);
+}
+
+function showVersion() {
+  console.log(packageJson.version);
+}
+
+async function main() {
+  if (args.includes('--help') || args.includes('-h')) {
+    showHelp();
+    process.exit(0);
+  }
+
+  if (args.includes('--version') || args.includes('-v')) {
+    showVersion();
+    process.exit(0);
+  }
+
+  switch (command) {
+    case 'start':
+    case undefined:
+      await import('../src/index.js');
+      break;
+
+    case 'accounts': {
+      const subCommand = args[1] || 'add';
+      process.argv = ['node', 'accounts-cli.js', subCommand, ...args.slice(2)];
+      await import('../src/cli/accounts.js');
+      break;
+    }
+
+    case 'help':
+      showHelp();
+      break;
+
+    case 'version':
+      showVersion();
+      break;
+
+    default:
+      console.error(`Unknown command: ${command}`);
+      console.error('Run "codex-claude-proxy --help" for usage information.');
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

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