@pikoloo/codex-proxy 1.0.6

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,199 @@
+# Codex Claude Proxy
+
+![Codex Proxy dashboard screenshot](./images/dashboard-screenshot.png)
+
+_Current dashboard preview: a real capture of the local Web UI with the macOS-style glass layout._
+
+[![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/surajmandalcell/codex-proxy?style=social)](https://github.com/surajmandalcell/codex-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.
+
+| Role | Details |
+| --- | --- |
+| Maintainer | Suraj Mandal |
+| GitHub | [surajmandalcell](https://github.com/surajmandalcell) |
+| Contact | [surajmandalcell@gmail.com](mailto:surajmandalcell@gmail.com) |
+| Package | [@pikoloo/codex-proxy](https://www.npmjs.com/package/@pikoloo/codex-proxy) |
+
+---
+
+## 🚀 Features
+
+- **Seamless Translation**: Translates Anthropic Messages API calls to ChatGPT Codex format.
+- **Model Mapping**: maps Claude model aliases to current OpenAI models, with direct GPT model IDs passed through.
+- **Personal Account Mode**: Uses the active ChatGPT account by default for local-only personal use, with account switching and auto-refresh.
+- **Web Dashboard**: Built-in macOS-style UI (`http://localhost:8081`) for managing accounts, viewing logs, adjusting settings, and testing prompts.
+- **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 binds to `127.0.0.1` by default.
+- **Direct Communication by Default**: Claude and GPT model requests connect directly to OpenAI/ChatGPT endpoints.
+- **No Rotation by Default**: Requests use the active account only. Multi-account rotation is disabled unless `CODEX_CLAUDE_PROXY_ENABLE_MULTI_ACCOUNT_ROTATION=true` is set.
+- **Third-Party Opt-In**: The explicit `kilo` model route uses Kilo/OpenRouter-backed free models only when `CODEX_CLAUDE_PROXY_ENABLE_KILO=true` is set. Default routing is OpenAI-only.
+- **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
+
+Install globally to use the CLI commands anywhere:
+
+```bash
+npm install -g @pikoloo/codex-proxy
+codex-proxy start
+```
+
+Or run the published package without a global install:
+
+```bash
+npx @pikoloo/codex-proxy@latest start
+```
+
+For release work from this checkout, use `make update` and `make publish`.
+
+The legacy `codex-claude-proxy` command remains available after installing this package.
+
+---
+
+## 🚦 Quick Start
+
+### 1. Start the Proxy
+
+```bash
+codex-proxy 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)
+codex-proxy accounts add
+
+# Headless/VM server (manual code input)
+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
+   ```
+
+4. **Run Claude**:
+   ```bash
+   claude
+   ```
+
+---
+
+## 🧠 Model Mapping
+
+The proxy automatically maps Claude model names to current OpenAI backend models. Direct `gpt-*` model IDs are passed through.
+
+| Requested Model ID | Upstream Model | Auth Required | Description |
+| :--- | :--- | :---: | :--- |
+| `claude-sonnet-4-5` | `gpt-5.5` | ✅ | Current default high-intelligence model |
+| `claude-opus-4-5` | `gpt-5.5` | ✅ | Current default high-intelligence model |
+| `claude-haiku-4` | `gpt-5.4-mini` | ✅ | OpenAI small-model lane |
+| `codex` | `gpt-5.3-codex` | ✅ | Latest Codex-optimized model |
+| `kilo` | Selected Kilo target | ❌ | Explicit third-party free-model route, disabled unless `CODEX_CLAUDE_PROXY_ENABLE_KILO=true` |
+
+---
+
+## 🛠️ Configuration & API
+
+### Web Dashboard
+
+The dashboard uses a clean desktop split-view layout with a compact toolbar, native-feeling glass surfaces, account management, live logs, settings, and prompt test panels. The screenshot at the top of this README is captured from the actual local app.
+
+Visit `http://localhost:8081` to:
+- **Manage Accounts**: Add, remove, or switch active ChatGPT accounts.
+- **Personal Mode**: Requests use the active account only unless multi-account rotation is explicitly enabled by environment variable.
+- **View Logs**: See real-time request/response logs for debugging.
+- **Test Models**: Run quick tests against the configured models.
+
+### 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/surajmandalcell/codex-proxy">
+    <img src="https://img.shields.io/github/stars/surajmandalcell/codex-proxy?style=social" alt="Star on GitHub">
+  </a>
+</div>

package/bin/cli.js

@@ -0,0 +1,118 @@
+#!/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 CLI_NAME = 'codex-proxy';
+const LEGACY_CLI_NAME = 'codex-claude-proxy';
+const args = process.argv.slice(2);
+const command = args[0];
+
+function showHelp() {
+  console.log(`
+${CLI_NAME} v${packageJson.version}
+
+Proxy server for using ChatGPT Codex models with Claude Code CLI.
+
+USAGE:
+  ${CLI_NAME} <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:
+  ${CLI_NAME} start
+  PORT=3000 ${CLI_NAME} start
+  ${CLI_NAME} accounts add
+  ${CLI_NAME} accounts add --no-browser
+  ${CLI_NAME} accounts list
+  ${CLI_NAME} accounts verify
+
+ALIASES:
+  ${LEGACY_CLI_NAME}    Legacy command name, still supported
+
+HEADLESS/VM USAGE:
+  1. Run: ${CLI_NAME} 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 "${CLI_NAME} --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