GPT for Claude Code

Run OpenAI GPT models inside Claude Code. Same CLI, same conversation history, same plugins and skills. Works with your existing ChatGPT Plus/Pro subscription via the public OAuth flow — no OpenAI API key required, no separate terminal tab, no context switching.

npm install -g gptcc
gptcc setup
gptcc hello        # end-to-end test in 5 seconds

ℹ️ About this project

gptcc is an extension for Claude Code, not a replacement or a fork. It uses only documented extension points — ANTHROPIC_BASE_URL, ANTHROPIC_CUSTOM_MODEL_OPTION, plugin hooks — the same mechanisms Claude Code's own docs show for LiteLLM, LM Studio, Ollama, and vLLM. No binary modification. No reverse engineering.

The ChatGPT OAuth flow is the exact public flow used by OpenAI's open-source Codex CLI, which OpenAI explicitly supports for personal, non-commercial use.

MIT licensed. Zero telemetry, zero tracking, zero monetization. Not affiliated with Anthropic or OpenAI. If either party would like this project to wind down, see SECURITY.md — we'll comply within 24 hours, no escalation.

Two ways to use it

Once installed, two workflows are available. You can switch between them any time — they're not mutually exclusive.

Mode 1 — Native GPT

Run the whole Claude Code session on GPT directly. Useful when you want GPT's behavior, reasoning, and tool use as the primary model while keeping the Claude Code CLI and workflow you already have configured.

# Pick one of these when launching
claude --model gpt-5.4-fast
claude --model gpt-5.4

# Or switch live from inside a session
/model

Best for: direct GPT sessions where you like Claude Code's CLI/tooling but want GPT to be the one reasoning and acting. Think of it as "Claude Code shell, GPT brain."

Mode 2 — Auto

Keep Claude as the conversation driver, but let GPT do most of the production work.

In Auto mode, Claude stays responsible for UI/UX direction, product judgment, architecture framing, and final integration quality, while GPT becomes the default worker for code writing, tests, bug analysis, and independent review.

The installed plugin ships with ready-made GPT subagents (gpt-implementer, gpt-reviewer, gpt-bug, gpt-arch) and Auto mode biases toward them when the task is implementation-heavy.

Best for: day-to-day coding where you want Claude to keep the big picture but have GPT do the first pass on implementation, tests, bug work, and review.

Cross-review (the killer use case)

After a non-trivial change, run Claude and GPT reviews in parallel and compare:

Agent(subagent_type: "code-reviewer",  prompt: "Review <files>...")
Agent(subagent_type: "gpt-reviewer",   prompt: "<same files, independent review>")

Common findings → fix. One-sided findings → verify before acting. This two-pass pattern catches noticeably more real issues than either model alone.

The /model picker

GPT shows up in Claude Code's /model picker alongside Claude models — select at any point in a session.

/model picker entries (added by gptcc v2.4)

gptcc setup is single-slot by default — Claude Code's built-in entries (Default, Opus, Sonnet, Haiku) are untouched, and gptcc adds exactly one custom entry:

| Display | Default? | When to use | |---|---|---| | Auto | yes | Claude drives the conversation and design judgment while GPT becomes the default worker for implementation, tests, bug analysis, and review. Best when you want GPT-first orchestration without writing Agent(...) calls yourself. | | GPT-5.4 | — | Run the session directly on GPT. Fastmode toggle controls whether you get the full or fast variant. Select via gptcc setup --model gpt-5.4-auto. |

To expose both entries at once, use gptcc setup --multi-slot (or --hybrid). These are opt-in; the default setup keeps Claude Code's layout minimally changed.

Settings

Three equivalent ways to toggle gptcc features (Fastmode, Auto review, SuperWork):

# from a shell
gptcc setting fastmode on
gptcc setting auto-review on
gptcc setting super-work on
gptcc setting list

# from inside Claude Code
/gptcc-fastmode on
/gptcc-auto-review on
/gptcc-superwork on
/gptcc-setting           # show current state

# from inside Claude Code (single entrypoint)
/gptcc list
/gptcc fastmode on
/gptcc auto-review on
/gptcc superwork on

All three write the same ~/.gptcc/config.json — edit it by hand if you prefer.

Upgrading from v2.3

• /model entry gpt-5.4-fast is removed. Run gptcc setting fastmode on for the same behavior.
• New entry Auto appears in /model. Select it for Claude-led, GPT-first orchestration.
• Your existing OAuth tokens, proxy config, and plugin hooks carry over.

Use cases

Five workflows people actually run with gptcc.

1. "Keep Claude in charge, but have GPT do most of the coding." Pick /model → Auto.

Claude keeps the flow, design judgment, and final integration pass. GPT handles the first pass on implementation, tests, bug analysis, and review-heavy coding work. This is the default collaboration story for gptcc.

2. "Claude wrote it, have GPT find the bugs." After Claude or GPT implements a non-trivial change, drop a single line:

Agent(subagent_type: "gpt-reviewer", prompt: "Review the diff on src/auth/")

GPT reads the same code independently and returns structured findings. Issues both models flag are almost always real — the false-positive rate on solo reviews drops sharply.

3. "I want GPT's reasoning for the architecture decision." For design questions with no single right answer:

Agent(subagent_type: "gpt-arch", prompt: "Evaluate the event-sourcing proposal in ADR-007")

A differently-trained model surfaces different tradeoffs. Faster than writing the same question twice in two different tools.

4. "This bug is subtle and Claude is stuck — get a second diagnosis."

Agent(subagent_type: "gpt-bug", prompt: "Why does `.sync()` return stale data on the third call?")

Root-cause analysis with xhigh effort, tool access for reading source and git history, returns a causal chain — not a guess.

5. "Run the whole session on GPT because this task is its strength." Specific math, certain coding patterns, niche libraries GPT trained more on:

claude --model gpt-5.4

Keeps your Claude Code CLI, plugins, skills, conversation history. Only the model changes.

Is it a good fit?

| ✅ Good fit | ⚠️ Poor fit | |---|---| | Claude-led flow with GPT doing most coding work | Tiny one-line edits where delegation overhead is not worth it | | Cross-review of non-trivial code | UI / Figma / visual judgment where Claude should stay primary | | Architecture second opinion | Environment / config / local-state tasks that require continuous local context | | Spec-driven generation of an isolated module | Long conversational detours where no production work is happening | | Using a specific GPT strength inside Claude Code | Situations where you want only Claude or only GPT, not orchestration |

Auto mode is most valuable when you want Claude to keep design and integration control while GPT does the bulk of the production work.

Table of Contents

• Install
• How it works
• Available models
• CLI commands
• Environment variables
• Auto-update behavior
• Architecture
• Security
• Troubleshooting
• Known limitations
• Uninstall
• Contributing
• FAQ
• License

Install

Prerequisites

• macOS, Linux, or Windows
• Node.js 18+
• Claude Code installed (claude on PATH, or set CLAUDE_BINARY)
• ChatGPT Plus or Pro subscription (required to reach GPT via Codex backend)

One command

npm install -g gptcc
gptcc setup

setup walks through five steps:

1. Confirm the install (one-time acknowledgement).
2. Check prerequisites.
3. ChatGPT login through your browser (Authorization Code + PKCE, same flow the official Codex CLI uses). Add --device for headless machines — it falls back to the Device Code flow.
4. Start the local proxy and write ANTHROPIC_BASE_URL to Claude Code settings once the proxy reports healthy.
5. Register ANTHROPIC_CUSTOM_MODEL_OPTION so GPT appears in the /model picker, then register the Claude Code plugin (for SessionStart auto-start of the proxy and the gpt-* subagents).

Verify with gptcc status:

  Proxy:     running (port 52532)
  Version:   2.2.1
  Auth:      valid (expires YYYY-MM-DD)
  Settings:  URL=OK  Picker=gpt-5.4-fast
  Platform:  darwin

Choose a default model

By default gptcc registers gpt-5.4-fast in the /model picker. To pick a different default at install time:

gptcc setup --model gpt-5.4
# or
GPTCC_DEFAULT_MODEL=gpt-5.4-mini gptcc setup

You can still invoke other GPT models inside the session (subagent frontmatter, direct claude --model <id>, etc.) — the proxy routes any gpt-* identifier to the Codex backend.

How it works

┌─────────────────┐
│   Claude Code   │
│ (Opus / Sonnet) │
└────────┬────────┘
         │ Anthropic Messages API
         │ ANTHROPIC_BASE_URL=http://127.0.0.1:52532
         ▼
┌─────────────────────────────────────────┐
│     gptcc — local proxy (127.0.0.1)     │
│                                         │
│     Route by model name:                │
│     ├─ claude-*  → Anthropic API        │
│     └─ gpt-*, o* → Codex backend        │
│        (with Claude→GPT prompt rewrite) │
└────────┬─────────────────┬──────────────┘
         │                 │
         ▼                 ▼
  api.anthropic.com    chatgpt.com/backend-api/codex
                       (OAuth, ChatGPT subscription)

Two components do the work:

1. Local proxy (lib/proxy.mjs) — translates Anthropic Messages API ↔ OpenAI Responses API, and rewrites Claude-specific system prompts into GPT-appropriate ones (strips Claude identity and meta-instructions, keeps only your CLAUDE.md content verbatim).

2. Plugin (plugin/) — registers the GPT subagents for Mode 2, and a SessionStart hook that ensures the proxy is running. Pure configuration; no binary modification anywhere.

Available models

| Model | Notes | |---|---| | gpt-5.4 | Flagship, 1M context, reasoning support | | gpt-5.4-fast | Same model, priority tier (1.5× speed, 2× credits) | | gpt-5.4-mini | Lightweight | | gpt-5.3-codex | Coding-specialized | | gpt-5.3-codex-spark | Real-time coding iteration | | gpt-5.2 | Previous generation |

CLI commands

| Command | Purpose | |---|---| | gptcc setup [--model <id>] | One-touch install | | gptcc setup --multi-slot | Install with 4-GPT picker mode | | gptcc login | Sign in via browser (default) | | gptcc login --device | Device-code flow for SSH / Docker / CI | | gptcc doctor | 5-layer self-diagnostic with fix hints | | gptcc hello | End-to-end smoke test | | gptcc status | Show proxy / auth / settings / platform | | gptcc proxy | Run the proxy in foreground (debug) | | gptcc uninstall | Remove everything | | gptcc help | Show help |

Environment variables

Basic

| Variable | Default | Purpose | |---|---|---| | GPT_PROXY_PORT | 52532 | Port the local proxy binds to | | GPTCC_DEFAULT_MODEL | claude-auto-opus | Default model registered in /model picker during setup | | GPTCC_NO_UPDATE | — | Set to 1 to disable the npm auto-update check | | GPTCC_DEBUG | — | Set to 1 for verbose proxy logging | | GPTCC_ACCEPT | — | Set to 1 to skip the interactive consent prompt (non-interactive installs) | | CLAUDE_BINARY | platform-specific | Path to the Claude Code binary |

Upstream endpoints (for testing / future API changes)

| Variable | Default | |---|---| | ANTHROPIC_API_ENDPOINT | https://api.anthropic.com | | CODEX_API_ENDPOINT | https://chatgpt.com/backend-api/codex | | OPENAI_TOKEN_ENDPOINT | https://auth.openai.com/oauth/token | | CODEX_AUTH_PATH | ~/.codex/auth.json | | CODEX_CLIENT_ID | public Codex CLI ID (same as openai/codex) |

Reasoning effort mapping (Claude budget_tokens → GPT effort)

• REASONING_LOW_MAX (default 2000)
• REASONING_MEDIUM_MAX (default 8000)
• REASONING_HIGH_MAX (default 20000)

Auto-update behavior

On most CLI invocations, gptcc checks npm for a newer version (24h cached). A new version is installed and the command re-runs automatically.

Skipped for: setup, login, uninstall, status, help (these need to work offline).

Disable globally with GPTCC_NO_UPDATE=1.

Architecture

gptcc/
├── bin/gptcc.mjs             # CLI entry
├── lib/
│   ├── login.mjs             # OAuth (browser + device code)
│   ├── routing.mjs           # Pure helpers shared with tests
│   ├── setup.mjs             # Cross-platform installer / uninstaller / status
│   ├── updater.mjs           # npm auto-update (24h cached)
│   └── proxy.mjs             # HTTP proxy (Anthropic ↔ OpenAI translation)
├── mcp/server.mjs            # MCP server (ask_gpt54, review_with_gpt54)
├── plugin/                   # Claude Code plugin
│   ├── .claude-plugin/
│   ├── hooks/
│   │   ├── hooks.json        # SessionStart hook
│   │   └── start-proxy.mjs   # cross-platform proxy starter
│   ├── agents/               # gpt-reviewer, gpt-bug, gpt-arch subagents
│   └── skills/gptcc-auto-delegate/ # Auto delegation rules + prompt templates
└── package.json

How the proxy handles prompts

Claude Code's system prompt is long (5–10 KB) and contains Claude-specific identity, workflow rules, and tone guidance. Forwarding that verbatim to GPT produces worse output than a clean prompt — GPT isn't Claude and shouldn't follow Claude's tone rules.

When a request targets a GPT model, the proxy:

1. Detects whether the system prompt is Claude Code's main prompt (not a subagent).
2. Extracts only the user's content (CLAUDE.md section).
3. Composes a minimal GPT system prompt: role + tool policy + user instructions.
4. Discards Claude identity, workflow rules, and tone guidance.

Subagent system prompts (from Agent(...)) are passed through as-is since they're already task-specific.

Security

Core properties:

• Proxy binds to 127.0.0.1 only (never exposed on a public interface).
• OAuth tokens in ~/.codex/auth.json with 0o600 permissions (platform-appropriate on non-POSIX systems).
• Auth file written atomically to prevent corruption.
• Anthropic passthrough restricted to /v1/* paths (SSRF prevention).
• OAuth Client ID is the public Codex CLI ID used by OpenAI's open-source codex tool.
• Zero telemetry, zero third-party services, zero monetization.

What this tool does not do:

• Modify the Claude Code binary.
• Reverse engineer anything.
• Send anything beyond the proxied API calls.
• Retain or log request contents.
• Collect or transmit user data to any third party.

For the full security policy and threat model, see SECURITY.md.

Troubleshooting

Proxy not running

gptcc proxy   # run in foreground to see startup errors

"Codex backend error" or 401

OAuth expired. Re-login:

gptcc login

GPT doesn't appear in /model picker

Usually a stale session — restart Claude Code. If still missing, check that settings.json contains the ANTHROPIC_CUSTOM_MODEL_OPTION key:

gptcc status

Plugin hook not starting proxy

Confirm the plugin is registered:

claude plugin list

Re-register: claude plugin add <path-to-gptcc>/plugin.

Known limitations

• ChatGPT Free accounts don't work — the Codex backend requires a paid ChatGPT subscription.
• No OpenAI API key path — this routes through the Codex backend via ChatGPT OAuth. API-key-based access would require a separate code path.
• Default installs expose one GPT entry in /model — for four GPT entries, install with gptcc setup --multi-slot (uses Claude Code's CLAUDE_CODE_USE_BEDROCK=1 mode plus the proxy's Bedrock-compatible endpoint).

Uninstall

One command. Restores everything. Safe to run any time.

gptcc uninstall
npm uninstall -g gptcc

Restores:

• Claude Code settings — ANTHROPIC_BASE_URL and ANTHROPIC_CUSTOM_MODEL_OPTION entries removed from ~/.claude/settings.json. Legacy keys from < 2.0 installs also cleaned up.
• Installed files — ~/.local/share/gptcc/ removed.
• Legacy launchd agents (macOS only) — any com.gptcc.* plist from < 2.0 installs unloaded and removed.
• Legacy binary backup (from < 2.0 installs) — if a ~/.local/bin/claude.backup exists from an earlier binary-adapter version, Claude Code is restored from it.

Does not remove:

• ~/.codex/auth.json — your ChatGPT OAuth tokens. Left in place because the official Codex CLI shares this file. Delete manually for a fully clean slate.
• Claude Code plugin registration — run claude plugin remove gptcc if you registered it.

Contributing

Community contributions are welcome. Start here:

• CONTRIBUTING.md — development setup, contribution workflows, coding style, and testing
• CODE_OF_CONDUCT.md — community expectations
• SECURITY.md — security policy and reporting
• CHANGELOG.md — release history

Good first contributions:

• Reports for new Claude Code or Codex API behaviors
• Proxy translation improvements (edge cases in streaming, tool use)
• New GPT subagent templates under plugin/agents/
• Windows and Linux platform polish

FAQ

Q: Is this an official Anthropic or OpenAI product? No. It's a small community tool built by and for developers who use both platforms. Not affiliated with, endorsed by, or sponsored by Anthropic or OpenAI. All trademarks belong to their respective owners; their use here is nominative fair use, solely to describe what this tool interoperates with.

Q: Does this violate Anthropic's Terms of Service? No reverse engineering, no binary modification, no bypass of authentication. gptcc uses only the documented Claude Code extension points:

• ANTHROPIC_BASE_URL for routing through a local proxy.
• ANTHROPIC_CUSTOM_MODEL_OPTION for registering the GPT model in the /model picker.
• Plugin hooks (SessionStart) for starting the proxy.

These are the same mechanisms Claude Code's documentation shows for LiteLLM, LM Studio, Ollama, and vLLM.

Q: Does this violate OpenAI's Terms of Service? OpenAI explicitly supports using the Codex OAuth flow outside the Codex CLI for personal, non-commercial use. gptcc uses the public OAuth client ID from OpenAI's open-source openai/codex — the flow is identical. OpenAI's stated restrictions ("not for commercial services, API resale, or multi-user applications") don't apply to a personal local dev tool like gptcc.

Q: Could my ChatGPT or Anthropic account be affected? Unlikely in normal use. The OAuth side is indistinguishable from the official Codex CLI, and the Claude side uses only documented extension points. If you're cautious, use a separate test ChatGPT account while you try it.

Q: Reversible? Yes, fully. gptcc uninstall removes everything and restores your settings.json. No binary is modified, so there's nothing to restore at the OS level.

Q: Will this become unnecessary? We hope so. If Claude Code adds a first-class multi-provider UI (say, a plugin that contributes picker entries and handles OpenAI auth natively), this tool is no longer needed and we'll happily deprecate it with a pointer to the official mechanism.

Q: How is this different from LiteLLM / OpenRouter? LiteLLM and OpenRouter are excellent general-purpose LLM gateways — use them when you want many providers, team deployments, or fine-grained cost control. Differences relevant to a solo Claude Code developer:

• Auth: gptcc uses your ChatGPT Plus/Pro subscription (OAuth). LiteLLM and OpenRouter require OpenAI API keys (separate billing).
• Scope: gptcc is Claude Code-specific — ships ready-to-use subagents (gpt-reviewer, gpt-bug, gpt-arch) and a Cross-review skill. LiteLLM is a general proxy; you still wire up prompts and agents yourself.
• Setup: npm install -g gptcc && gptcc setup vs a YAML config file.

If you already run LiteLLM for team cost control, keep doing that. If you're an individual developer with a ChatGPT subscription who wants GPT in Claude Code today, gptcc is the shorter path.

Q: How is this different from claude-code-router? claude-code-router is a great general router with many models. Differences:

• ChatGPT subscription support: gptcc's main value proposition. As of v2.1 we don't know of another tool that does this.
• Prompt optimization: gptcc rewrites the Claude Code system prompt for GPT (strips Claude identity, keeps your CLAUDE.md). The routing-only approach sends the full Claude prompt to GPT, which hurts GPT output.
• Built-in subagents: gptcc ships Cross-review patterns as ready-made subagents in the Claude Code plugin. Router leaves orchestration to you.

Q: Why not just use Codex CLI directly? If all you want is GPT in a terminal, Codex CLI is the right tool — faster, maintained by OpenAI, no translation overhead. gptcc exists for the integration case: you already invested in Claude Code (plugins, skills, CLAUDE.md, conversation history) and you want GPT to participate in that workflow. Cross-review and Agent(subagent_type: "gpt-*") patterns need both models in the same session — Codex CLI alone can't do that.

Q: Is this faster than Codex CLI for pure GPT work? No — it adds a small proxy hop. Use this for integration with Claude Code workflows, not for faster GPT alone.

Q: Can GPT match Claude's quality inside Claude Code? Varies by task. GPT does some things better, Claude does others. The value is having both available in the same session, not one being universally better. Most of our own usage is Claude as the main session with selective GPT delegation (code review, independent second opinion, specialized generation tasks).

Q: Why strip Claude's system prompt when calling GPT? Claude Code's system prompt contains Anthropic-specific identity, tone guidance, and workflow rules tuned for Claude. Feeding those to GPT makes GPT perform worse than giving it a clean, task-specific prompt. So when the proxy routes to a GPT model, it extracts only your CLAUDE.md content and composes a minimal GPT-appropriate system prompt.

Q: Why only one GPT model in the /model picker? ANTHROPIC_CUSTOM_MODEL_OPTION currently accepts a single entry. You can still use other GPT variants inside the session — the proxy routes any gpt-* identifier to the Codex backend. A future release (Phase B) will add a Bedrock-compatible endpoint path so multiple GPT entries can share the picker at once.

License

MIT — see LICENSE.

Not affiliated with, endorsed by, or sponsored by Anthropic, OpenAI, or ChatGPT. All trademarks belong to their respective owners; their use in this repository is nominative fair use, solely to describe what this tool interoperates with.