Skip to content

Use Claude Code with your ChatGPT, Kimi, Cursor or Grok subscription via a local Anthropic-compatible proxy

Rust

add README

Raine Virta4791827e595e
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..571c232
--- /dev/null
+++ b/README.md
@@ -0,0 +1,326 @@
+# claude-openai-proxy
+
+`claude-openai-proxy` is a local HTTP proxy that lets
+[Claude Code](https://www.anthropic.com/claude-code) call OpenAI's Codex
+Responses API using a **ChatGPT Pro/Plus subscription** — no Anthropic API key,
+no OpenAI API key.
+
+It translates Anthropic-shaped `/v1/messages` requests to the Responses API,
+calls `chatgpt.com/backend-api/codex/responses` with your ChatGPT OAuth token,
+and streams the response back in Anthropic SSE format. Claude Code talks to it
+over `ANTHROPIC_BASE_URL` and doesn't know the difference.
+
+[Quick start](#quick-start) · [How it works](#how-it-works) ·
+[Configuration](#configuration) · [Limitations](#limitations)
+
+## Why?
+
+You're already paying for ChatGPT Plus or Pro. You like the Claude Code UX (TUI,
+slash commands, hooks, skills, plugins). This proxy lets you use the former to
+pay for the latter — running Claude Code against GPT-5.x through your existing
+subscription.
+
+## Quick start
+
+### 1. Install
+
+```sh
+git clone https://github.com/raine/claude-openai-proxy
+cd claude-openai-proxy
+bun install
+```
+
+Requires [Bun](https://bun.sh) 1.3+.
+
+### 2. Authenticate with ChatGPT
+
+Open a browser (PKCE flow):
+
+```sh
+bun src/cli.ts auth login
+```
+
+Or, on a headless machine (device code flow):
+
+```sh
+bun src/cli.ts auth device
+```
+
+Either command prints a URL. Sign in with your **ChatGPT Plus/Pro account**. The
+access and refresh tokens are stored at
+`~/.config/claude-openai-proxy/auth.json` with 0600 permissions.
+
+Verify it stuck:
+
+```sh
+bun src/cli.ts auth status
+```
+
+### 3. Start the proxy
+
+```sh
+bun src/cli.ts serve
+```
+
+Defaults to `http://127.0.0.1:11434` (loopback only). Override with
+`PORT=18765 bun src/cli.ts serve`.
+
+### 4. Point Claude Code at it
+
+One-shot:
+
+```sh
+ANTHROPIC_BASE_URL=http://localhost:11434 \
+ANTHROPIC_AUTH_TOKEN=unused \
+ANTHROPIC_MODEL=gpt-5.4 \
+CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
+ claude
+```
+
+## Supported models
+
+Set `ANTHROPIC_MODEL` to a model your ChatGPT subscription is allowed to use.
+Confirmed working on **Plus**:
+
+- `gpt-5.4`
+- `gpt-5.3-codex`
+
+Likely available on **Pro / Enterprise** (not tested by this project, but part
+of the Codex CLI allowlist):
+
+- `gpt-5.1-codex`, `gpt-5.1-codex-max`, `gpt-5.1-codex-mini`
+- `gpt-5.2`, `gpt-5.2-codex`
+- `gpt-5.4-mini`
+
+If you pass a model your account isn't entitled to, upstream returns a 400 like
+`"The 'gpt-5.1-codex' model is not supported when using Codex with a ChatGPT account."`
+— the proxy surfaces it verbatim.
+
+## How it works
+
+```mermaid
+sequenceDiagram
+ autonumber
+ participant CC as Claude Code
+ participant P as claude-openai-proxy
+ participant AUTH as auth.openai.com
+ participant CGX as chatgpt.com/<br/>backend-api/codex
+
+ Note over P,AUTH: One-time: PKCE or device OAuth<br/>tokens cached at<br/>~/.config/claude-openai-proxy/auth.json
+
+ CC->>P: POST /v1/messages (Anthropic shape, stream: true)
+
+ alt access token expiring
+ P->>AUTH: POST /oauth/token (refresh_token)
+ AUTH-->>P: new access + refresh
+ end
+
+ P->>P: translate request<br/>• strip max_tokens / temperature / cache_control<br/>• system blocks → top-level "instructions"<br/>• tool_use.id = call_id (identity)<br/>• prompt_cache_key = session id
+ P->>CGX: POST /responses<br/>Bearer + ChatGPT-Account-Id + originator
+ CGX-->>P: Responses API SSE<br/>(output_item.*, output_text.delta, function_call_arguments.*, codex.rate_limits, response.completed)
+ P->>P: reducer: typed events<br/>(text/tool start/delta/stop, finish)
+ P-->>CC: Anthropic SSE<br/>(message_start, content_block_*, message_delta, message_stop)
+```
+
+Key decisions:
+
+- **Transport:** HTTP POST (not WebSocket). The backend accepts both; POST is
+ simpler and battle-tested by opencode.
+- **State:** stateless replay every turn — no `previous_response_id`, no
+ `store: true`. Claude Code sends the full history each turn anyway;
+ `prompt_cache_key` keyed off `x-claude-code-session-id` lets the upstream
+ auto-cache most of it (typically 70%+ hit rate on follow-up turns).
+- **Tool IDs:** identity mapping. Anthropic `tool_use.id` = OpenAI `call_id`
+ verbatim.
+- **Reasoning:** dropped. Responses-style reasoning summaries can't be faked as
+ Anthropic `thinking` blocks with valid signatures, so they're omitted.
+- **System prompt:** Anthropic `system` blocks are concatenated into the
+ Responses API top-level `instructions` field. The rotating
+ `x-anthropic-billing-header:` block Claude Code injects is stripped so it
+ doesn't invalidate the prompt cache on every turn.
+- **Stripped before upstream:** `max_tokens`, `temperature`, `top_p`,
+ `cache_control`, `thinking`, `context_management`, `metadata`, and all
+ `anthropic-beta` headers.
+
+## Commands
+
+| Command | Description |
+| ----------------------------- | ----------------------------------------- |
+| [`serve`](#serve) | Start the proxy on `PORT` (default 11434) |
+| [`auth login`](#auth-login) | Browser OAuth (PKCE) |
+| [`auth device`](#auth-device) | Device-code OAuth (headless) |
+| [`auth status`](#auth-status) | Show account ID and token expiry |
+| [`auth logout`](#auth-logout) | Delete the stored auth file |
+
+---
+
+### `serve`
+
+Starts the HTTP proxy and blocks. Binds to `127.0.0.1` only. Logs to
+`$XDG_STATE_HOME/claude-openai-proxy/proxy.log` (rotated at 20 MiB). Set
+`CCXP_LOG_STDERR=1` to mirror log lines to stderr while running.
+
+```sh
+claude-openai-proxy serve
+PORT=18765 claude-openai-proxy serve
+CCXP_LOG_STDERR=1 claude-openai-proxy serve
+```
+
+Prints the exact `ANTHROPIC_BASE_URL` / `ANTHROPIC_MODEL` env vars to export on
+startup. Refuses to start traffic until `auth login` (or `auth device`) has
+stored a token.
+
+---
+
+### `auth login`
+
+Runs the PKCE browser flow against `auth.openai.com` using the Codex CLI's
+client ID. Prints a URL, opens a local callback listener on port 1455, waits for
+the browser to redirect back, and stores the resulting access / refresh tokens
+at `~/.config/claude-openai-proxy/auth.json` (mode 0600). The process exits
+automatically once the tokens are saved.
+
+```sh
+claude-openai-proxy auth login
+```
+
+Sign in with your **ChatGPT Plus/Pro account** — not an OpenAI API account. The
+token file includes the extracted `chatgpt_account_id` so the proxy can set the
+`ChatGPT-Account-Id` header on every upstream call.
+
+---
+
+### `auth device`
+
+Same OAuth flow, but for headless machines. Prints a short user code and a URL;
+you enter the code from any browser on any other device, and the CLI polls
+`auth.openai.com` until you authorize, then stores the token.
+
+```sh
+claude-openai-proxy auth device
+```
+
+Useful over SSH, inside a container, or on any host that can't open a browser.
+
+---
+
+### `auth status`
+
+Shows whether credentials are stored, the account ID, and how long until the
+access token expires. Non-zero exit if no auth is present.
+
+```sh
+claude-openai-proxy auth status
+```
+
+Example output:
+
+```
+Account: 79342a5e-57b7-44ea-bfdc-a83ba070dad6
+Expires: 2026-04-28T16:46:04.827Z (in 863946s)
+File: /Users/you/.config/claude-openai-proxy/auth.json
+```
+
+The proxy refreshes the access token 5 minutes before expiry with a
+single-flight guard, so concurrent requests never trigger stampedes of refresh
+calls.
+
+---
+
+### `auth logout`
+
+Removes `~/.config/claude-openai-proxy/auth.json`. No server call is needed; the
+refresh token just becomes dead.
+
+```sh
+claude-openai-proxy auth logout
+```
+
+Run `auth login` again to re-authenticate.
+
+---
+
+### Endpoints
+
+The proxy speaks enough of the Anthropic API for Claude Code:
+
+- `POST /v1/messages` — the main turn endpoint (streaming and non-streaming)
+- `POST /v1/messages?beta=true` — same (Claude Code always sends `?beta=true`)
+- `POST /v1/messages/count_tokens` — local token count via `gpt-tokenizer`
+ (o200k_base); used by Claude Code's compaction logic
+- `GET /healthz` — liveness check
+
+## Configuration
+
+Settings are environment variables on the proxy process, not a config file.
+
+| Variable | Default | Purpose |
+| ----------------- | ---------------- | ------------------------------- |
+| `PORT` | `11434` | Proxy listen port |
+| `XDG_STATE_HOME` | `~/.local/state` | Base dir for `proxy.log` |
+| `CCXP_LOG_STDERR` | unset | Also mirror log lines to stderr |
+
+### Files
+
+- `~/.config/claude-openai-proxy/auth.json` — OAuth tokens, 0600
+- `$XDG_STATE_HOME/claude-openai-proxy/proxy.log` — JSON-lines log, rotated at
+ 20 MiB. Secrets (`authorization`, `access`, `refresh`, `id_token`,
+ `ChatGPT-Account-Id`, …) are redacted before write.
+
+### Multiple Claude Codes, one proxy
+
+Several Claude Code instances can share a single proxy. Each request carries its
+own `x-claude-code-session-id`, which becomes the upstream `prompt_cache_key`,
+so sessions don't poison each other's cache. All sessions draw from the same
+ChatGPT rate-limit budget, so be aware that one chatty session affects the
+others.
+
+## Limitations
+
+- **Terms of service:** using the Codex backend from a non-official client is
+ the same gray area opencode occupies. Use at your own risk.
+- **Rate limits:** shared across all clients of your ChatGPT account.
+ `codex.rate_limits.limit_reached` is surfaced as HTTP 429 with `retry-after`.
+- **Image inputs in tool results:** Responses API `function_call_output` only
+ takes a string, so image blocks nested inside `tool_result` are replaced with
+ a `[image omitted: <media_type>]` placeholder. Top-level user-message images
+ do pass through.
+- **Reasoning blocks:** not forwarded to Claude Code (dropped), even if the
+ upstream model produced them.
+- **Session title generation:** Claude Code's parallel title-gen request is
+ forwarded to Codex like any other structured-output request — costs a handful
+ of tokens per session rather than being stubbed.
+- **OpenAI-flavored `output_config.format`:** translated to Responses API
+ `text.format` (json_schema with `strict: true`); other Anthropic-specific
+ `output_config` fields are dropped.
+
+## Development
+
+```sh
+bunx tsc --noEmit # typecheck
+bun src/cli.ts serve # run locally
+tail -f ~/.local/state/claude-openai-proxy/proxy.log | jq .
+```
+
+The core logic lives in:
+
+- `src/translate/request.ts` — Anthropic → Responses API request
+- `src/translate/reducer.ts` — Responses SSE state machine (typed events)
+- `src/translate/stream.ts` — ReducerEvent → Anthropic SSE
+- `src/translate/accumulate.ts` — ReducerEvent → Anthropic JSON (non-streaming)
+- `src/codex/client.ts` — bearer + account-id headers, 401 refresh-retry
+- `src/auth/manager.ts` — refresh-ahead with single-flight guard
+
+## Credits
+
+The OAuth flow, client ID, endpoint URL, and JWT claim extraction are ported
+from [opencode](https://github.com/sst/opencode)'s `codex.ts` plugin.
+
+## Related projects
+
+- [opencode](https://github.com/sst/opencode) — the AI coding agent that proved
+ the Codex-via-subscription pattern works in TypeScript
+- [claude-history](https://github.com/raine/claude-history) — search Claude Code
+ conversation history from the terminal
+- [git-surgeon](https://github.com/raine/git-surgeon) — non-interactive
+ hunk-level git staging for AI agents