gptCode

Run the Claude Code terminal experience with GPT models and your existing Codex ChatGPT login.

gptCode starts the stock claude executable with a session-local Anthropic-compatible proxy. Claude Code keeps handling the terminal UI, permissions, tools, project instructions, skills, hooks, MCP, sessions, and subagents. The proxy translates Anthropic Messages requests into OpenAI Responses requests authenticated through Codex OAuth.

Important

gptCode is an independent compatibility project. It is not affiliated with or supported by Anthropic or OpenAI. The Codex subscription backend can change; pin tested CLI versions and run gptcode doctor after upgrading either CLI.

Why this exists

Claude Code and Codex have different strengths. gptCode combines Claude Code's mature terminal harness with GPT reasoning models without modifying either installed CLI.

Native-first design contract

Claude Code is the product shell and remains authoritative for its terminal UI, permissions, tools, skills, MCP, hooks, agents, Workflows, session history, model and effort menus, retries, and compaction. gptCode is a provider-protocol adapter, not a replacement agent framework.

When the Anthropic and Codex protocols differ, gptCode follows this order:

1. Use a documented Claude Code setting or built-in feature.
2. Translate the standard Anthropic request/response semantics faithfully at the provider boundary.
3. If faithful translation is impossible, fail clearly instead of silently inventing different behavior.

Custom schedulers, transcript formats, task runners, context summarizers, and parallel agent systems are out of scope. A compatibility shim must be minimal, isolated from saved Claude state, and covered by a regression test.

claude (isolated gptCode profile)
        │ Anthropic Messages API
        ▼
127.0.0.1:<random port>  gptCode proxy
        │ OpenAI Responses API
        ▼
ChatGPT Codex backend  ◄── short-lived access token owned by Codex CLI

Requirements

• Node.js 20 or newer.
• Claude Code CLI 2.1.203 or newer installed and available as claude (required for the native model/effort menus used by gptCode).
• Codex CLI installed and available as codex.
• A ChatGPT login in Codex: run codex login, then confirm with codex login status.
• Codex file-based credential storage. If you explicitly changed cli_auth_credentials_store to keyring, gptCode cannot read the resulting short-lived access token.

The current release is live-tested on Windows 11 with Node 22.17.0, Claude Code 2.1.211, and Codex CLI 0.144.4. The offline suite targets Windows, macOS, and Linux on Node 20 and 22.

Install

From an existing checkout:

npm install -g .
gptcode doctor

Directly from the public GitHub repository:

npm install -g github:ItayCohen-Prog/gptCode#v1.1.1
gptcode doctor

After the package is published to npm:

npm install -g gptcode
gptcode doctor

Then start it from any project:

gptcode

The npm bin entry creates the appropriate gptcode, gptcode.cmd, and gptcode.ps1 shims. The repository wrappers are also available for checkout-based development.

Everyday use

gptcode                                      # interactive session
gptcode -p "Explain this repository"        # Claude Code print mode
gptcode --effort xhigh                       # native Claude effort control
gptcode --model sonnet                       # balanced family mapping
gptcode --gpt-model gpt-5.6-terra            # direct GPT starting selection
gptcode --clean                              # ignore project/local settings
gptcode doctor                               # prerequisites and auth check

Most unrecognized options pass through to Claude Code. This includes permission modes, tool controls, MCP configuration, output formats, session resume, foreground worktrees/agents, and structured output. Detached --bg, --background, and --tmux modes are rejected because their worker process would outlive the session-local proxy. Claude installation commands (update, upgrade, install) are also blocked so gptCode cannot modify the shared normal-Claude executable. gptCode consumes --model, --gpt-model, --clean, and --settings; family model names are normalized to their real GPT IDs, and user settings are merged into a temporary file inside the isolated gptCode profile. The former --no-gptcode-plugin flag remains an accepted no-op for script compatibility.

Model and effort controls

At startup, gptCode reads the visible GPT catalog from the current Codex OAuth account and feeds it into Claude Code's built-in /model picker. The selected model occupies Claude's custom row so the startup card immediately shows its raw GPT ID; the remaining account models appear as gateway rows. The exact list is account- and rollout-dependent. A current catalog can include GPT-5.6 Sol, Terra, and Luna alongside GPT-5.5, GPT-5.4, GPT-5.4 Mini, and GPT-5.3 Codex Spark. Hidden and non-GPT backend entries are not advertised.

Use Claude's native /model, /effort, --model, and --effort controls for normal work. Press Enter in /model to save a choice inside gptCode's isolated Claude profile, or s for the current session only. Saved choices never change normal Claude Code's settings. If a saved or resumed model is no longer available to the account, gptCode fails clearly instead of silently switching the session to another model.

Claude Code's gateway API exposes model IDs and display names but not per-model effort capabilities. The native /effort menu therefore shows its standard choices even when a GPT model supports fewer levels. gptCode clamps an unsupported choice to the closest supported level and the footer shows the effective value; for example, max becomes xhigh on a model whose catalog stops at xhigh. Ultracode uses GPT xhigh reasoning with Claude Code's workflow preset.

Some shell-owned UI copy cannot be renamed by a gateway: the immutable Default row may mention an organization, and native /status can expose a Claude-compatible gateway ID. The gptCode footer canonicalizes that ID to the real GPT model and effective effort. No separate GPT status command is needed; use native /status plus the footer.

Use Claude's built-in /status command for the session version, ID, working directory, active GPT model, and loopback connection. It is shell-owned, opens immediately, and consumes no GPT turn. The always-visible gptCode footer adds the current effort and truthful Codex OAuth backend label. Together they replace the former /gptcode:gpt-status skill, which was removed because invoking a custom status skill unnecessarily consumed a model turn.

OAuth only—no API key

gptCode does not use OPENAI_API_KEY, does not fall back to API billing, and strips ambient OpenAI and Anthropic API-billing variables from the launcher, proxy, and Claude child while preserving the Codex OAuth credential path.

The authentication flow is deliberately narrow:

1. gptCode reads the short-lived access token already cached by Codex.
2. If that token is close to expiry or the backend returns 401, gptCode starts the installed codex app-server and requests account/read with refreshToken: true.
3. Codex performs its normal managed OAuth refresh.
4. gptCode rereads only the resulting access token.

gptCode never uses, copies, exposes, or writes the Codex refresh token and never rewrites ~/.codex/auth.json. It parses Codex's credential document only to extract the short-lived access token. Codex remains the sole owner of its login cache. The cache is shared by default, so the Codex process may update it during a normal OAuth refresh.

Some subscription models are gated by the installed Codex client version. gptCode asks the installed codex app-server for its public client identity and uses that identity for backend compatibility, while also sending x-gptcode-version so requests remain attributable to gptCode. It does not claim an invented client version. If the installed Codex CLI cannot report a compatible identity, startup fails with an upgrade-oriented error instead of falling back to an API key.

For a completely separate Codex login cache, set GPTCODE_CODEX_HOME to a dedicated directory and run Codex login against that directory once:

$env:GPTCODE_CODEX_HOME = "$HOME\.gptcode\codex"
$env:CODEX_HOME = $env:GPTCODE_CODEX_HOME
codex login
Remove-Item Env:CODEX_HOME
gptcode

Persist GPTCODE_CODEX_HOME in your shell profile if you choose this stricter mode. Do not copy auth.json between homes; log in normally so each profile owns its refresh-token lifecycle.

When GPTCODE_CODEX_HOME is set, gptCode ignores any ambient CODEX_ACCESS_TOKEN and removes it from the Codex refresh child. The dedicated auth file is therefore a hard credential boundary, not merely a path preference.

Isolation from normal Claude Code and Codex

Claude isolation is a release invariant, not a convention. Codex OAuth ownership is kept separate, while its normal login cache is shared by default so the existing login works without a second sign-in:

Surface	Normal CLI	gptCode
Claude user state	~/.claude	~/.gptcode/claude via CLAUDE_CONFIG_DIR
Legacy picker migration state	none	~/.gptcode/picker-state.json, read only for profiles created by the pre-discovery two-row picker
Claude session history	normal Claude profile	isolated gptCode profile
Claude plugins/skills/hooks	normal Claude profile	isolated gptCode profile
Provider environment	caller's normal environment	protected loopback routing; provider credentials and proxy variables stripped from child
Local proxy	none	127.0.0.1 random port and random per-launch token
Codex refresh token	owned by Codex	never accessed, used, exposed, or written by gptCode
Codex access token	owned/cached by Codex	read by the proxy only; stripped from Claude and its tools

Project-owned files such as CLAUDE.md, .claude/settings.json, project skills, and .mcp.json still load by default because they are part of the project being worked on. gptcode --clean limits Claude setting sources to the isolated user profile when troubleshooting.

Running gptCode does not set persistent environment variables, modify PATH, install a Claude plugin, or write to normal Claude user settings. Its isolated Claude process tree carries the inert child-only marker GPTCODE_ACTIVE=1 so downstream launchers can recognize and scrub inherited gptCode provider routing before starting normal Claude Code; the marker does not change Claude behavior. The isolated Claude child has telemetry, error reporting, and its auto-updater disabled. Gateway model discovery still requires Claude's model-list request, so gptCode cannot use Claude's broader "disable all nonessential traffic" switch. The proxy may ask Codex itself to refresh the shared login cache when required; use GPTCODE_CODEX_HOME if even that normal Codex-owned update must be separated. Uninstalling the npm package does not remove ~/.gptcode; delete that directory separately only if you also want to delete gptCode session history and settings.

Configuration

Create a per-user starter file:

gptcode config init
gptcode config path

The default path is ~/.gptcode/config.json. Set GPTCODE_CONFIG to use another file or copy gptcode.config.example.json.

Important fields:

• server.heartbeatMs: maximum downstream silence before gptCode emits an SSE ping (30 seconds by default), keeping long reasoning turns alive without changing their content.
• models.default: fallback GPT model and effort.
• models.discovery: discover the current OAuth account's visible GPT catalog at startup (recommended and enabled by default).
• models.picker: one or more fallback models, display-name overrides, legacy ID aliases, direct-request fallback efforts, and fallback contextWindow values. When discovery succeeds, unavailable configured models are not advertised.
• models.families: Opus/Sonnet/Haiku compatibility mappings. Missing targets are reconciled to the live catalog before launch.
• reasoning.summary: reasoning summary mode; set null to disable.
• reasoning.mode: optional backend reasoning mode.
• reasoning.budgetTiers: legacy extended-thinking budget mapping.
• text.verbosity: optional Responses verbosity.
• subagent: Claude Code Agent/Workflow routing policy. The default force: false preserves native inheritance and explicit per-agent choices. Set force: true only when you intentionally want every worker pinned to the configured model/effort.
• systemPreamble: short identity/adapter preamble; the default does not prescribe tools, agents, Workflows, retries, reviews, or completion policy. Set null or an empty string to disable.
• launcher.statusLine: enable the backend-aware gptCode footer.
• launcher.enableToolSearch: preserve Claude MCP tool search when using a third-party base URL.
• launcher.env: additional child-only environment values. Provider routing and credential variables are reserved and cannot be overridden here.

gptCode does not prune user/assistant history and does not implement a custom summarizer. It gives Claude Code's native auto-compactor a fixed 270,000-token window; Claude Code decides when and how to run summary compaction, including inside native subagents and Workflows. GPT-5.3-Codex-Spark is omitted from /model because its 128,000-token window is incompatible with that session-wide setting.

Claude Code also sends the standard Anthropic context_management contract before summary compaction. Because the Codex Responses endpoint does not accept that field, gptCode applies its documented tool-result and thinking-block edits to the upstream request only, returns Anthropic-compatible edit statistics, and uses the same edited view for token counting and generation. The isolated Claude transcript remains complete and unmodified. Unsupported server-side summary edits fail clearly rather than being reimplemented with a bespoke gptCode summarizer; Claude Code's own /compact and auto-compaction remain authoritative.

The bundled claude-api provider skill is user-invocable-only in gptCode's temporary isolated Claude settings. This uses Claude Code's native skillOverrides behavior: the skill cannot be auto-selected by a Workflow or subagent merely because a task mentions Claude Code, but users can still run /claude-api intentionally. gptCode does not rewrite skill payloads or inject a custom skill-routing prompt.

Supported environment variables:

Variable	Purpose
GPTCODE_HOME	Override the gptCode state root
GPTCODE_CONFIG	Override the JSON configuration path
GPTCODE_CODEX_HOME	Use a separate Codex OAuth profile
GPTCODE_CLAUDE_BIN	Override the Claude executable
GPTCODE_CODEX_BIN	Override the Codex executable
GPTCODE_LOG=debug	Show proxy diagnostics
GPTCODE_DUMP=<dir>	Write translated requests for debugging; sensitive

Translation coverage

Capability	Status
Text and streaming deltas	Tested
Claude client tools and parallel function calls	Tested, including interleaving
Tool-result text and images	Tested translator path
Image and base64 PDF input	Implemented
Extended reasoning replay across tool turns	Tested with encrypted reasoning items
Native Claude effort slider	Live-tested
Structured output / --json-schema	Object-root schemas mapped, unit-tested, and live-tested; non-object tool schemas fail clearly because both provider tool contracts require object inputs
Strict function schemas	Mapped and unit-tested
Built-in Agent and Workflow routing	Live-tested with genuine Claude Agent/Workflow fan-out; defaults to native model/effort inheritance
Claude context management	Native tool-result/thinking edits mapped at the provider boundary; saved history remains untouched
MCP/tool search	Enabled; requires broader live regression coverage
Project skills, hooks, commands, and agents	Handled by Claude Code in the isolated profile
Anthropic server-hosted tools	Explicitly rejected; they are not silently dropped
Token counting	Conservative content-density approximation using the same native context-management view as generation; not model-exact

Deliberate compatibility behavior

• Sampling fields that GPT reasoning models reject (temperature, top_p, top_k) are removed.
• Unsupported input blocks fail with a clear 400 instead of silently changing the prompt.
• Malformed function-call arguments fail translation instead of becoming {}.
• Codex's subscription backend is stream-only; gptCode aggregates streams when Claude requested JSON.
• GPT context-window failures are returned as Anthropic invalid_request_error / Prompt is too long, allowing Claude Code's native recovery path instead of misclassifying them as generic server errors.
• The backend currently rejects max_output_tokens, so gptCode cannot enforce Claude's requested output cap upstream.
• Claude's --output-format json cost fields are calculated from the virtual Claude family and are not authoritative for ChatGPT-plan usage. Use native /status plus the gptCode footer for current routing; use Codex/ChatGPT account surfaces for quota information.
• Detached/background Agent View modes are intentionally rejected until gptCode has a durable isolated proxy broker. The launcher blocks detached flags and interactive agents, and disables the in-session Agent View affordance; foreground built-in Agent and Workflow tools remain supported.

CLI reference

gptcode [claude options]       Launch Claude Code through gptCode
gptcode doctor                Check Node, Claude, Codex, OAuth, config, isolation
gptcode auth status           Show safe OAuth readiness metadata
gptcode config path           Print the active config path
gptcode config init           Create a starter config without overwriting
gptcode serve --port 4141     Run only the local proxy
gptcode --help                Show help
gptcode --version             Show package version

gptcode serve prints a newly generated local bearer token. Treat that terminal output as sensitive. Normal gptcode sessions keep the token internal. doctor and auth status perform a bounded, non-generation request to verify that the Codex backend accepts the cached OAuth access token.

Troubleshooting

Start with:

gptcode doctor

Codex OAuth is not available

codex login
codex login status
gptcode auth status

If Codex stores credentials in the OS keyring, switch Codex to file storage or use a dedicated GPTCODE_CODEX_HOME configured for file storage. gptCode will not ask for an API key.

Claude starts normally instead of showing gptCode

Confirm the command path:

Get-Command gptcode
gptcode --version

Reinstall from the checkout with npm install -g . if the shim points to an older package.

A model disappeared or stopped working

The GPT model IDs available to ChatGPT/Codex accounts can change. Upgrade Codex, run gptcode doctor, and start a fresh session to refresh /model. A resumed session whose saved model disappeared is rejected rather than silently redirected. With models.discovery: false, update the explicit models.picker fallback list yourself.

Inspect a failed translation

$env:GPTCODE_LOG = "debug"
gptcode -p "small reproduction"
Remove-Item Env:GPTCODE_LOG

Use GPTCODE_DUMP only in a private directory and remove dumps after debugging; they may include prompts, file content, and tool results.

Development

The runtime has no npm dependencies.

npm test
npm run verify:package
npm run check

The offline suite covers OAuth selection and non-mutation, dedicated-profile boundaries, request/response translation, streaming, CRLF framing, parallel calls, structured output, refusals, config merging, proxy authentication, model/effort control, launcher isolation, native subagent inheritance/observability, unsafe detached-mode rejection, and package contents.

See CONTRIBUTING.md, SECURITY.md, and CHANGELOG.md.

Release checklist

• npm run check passes on Node 20 and 22 across Windows, macOS, and Linux.
• A packed-tarball install exposes gptcode --help and gptcode doctor.
• A live OAuth smoke test confirms the backend model and effort.
• Normal ~/.claude and Codex auth bytes are unchanged when no refresh is required.
• Interrupting Claude terminates the owned proxy.
• README compatibility claims match explicit tests.
• No secrets, debug dumps, tests, or development scripts appear in the tarball.
• The public GitHub release is tagged v<package version> and npm trusted publishing is configured for .github/workflows/publish.yml.

License

MIT