gptcode

Agentic coding CLI that uses your ChatGPT account (OAuth) as the primary model backend, with OpenAI API key failover when usage limits hit — inspired by openai-oauth and Claude Code–style install/UX.

Not affiliated with OpenAI. Unofficial ChatGPT/Codex OAuth access may conflict with OpenAI Terms, can break without notice, and may risk your account. Use only your own credentials. Do not pool or share tokens.

Requirements

• Node.js ≥ 20
• A ChatGPT account (free or Plus) or an OpenAI API key

Install

npm install -g @roniotakahashi/gptcode

Then sign in once:

gptcode login        # opens browser — completes ChatGPT OAuth
gptcode status       # confirms signed-in state and active model

If the gptcode package name is taken on npm, publish under a scope (e.g. @yourname/gptcode) — the bin entry still exposes the gptcode command.

Quick start

gptcode                        # interactive — type freely; /help /model /exit
gptcode fix the flaky test     # one-shot — no flags needed

In interactive mode:

❯ explain src/app.ts
❯ /model                       # ↑/↓ picker, Enter to select
❯ /model gpt-5.6-terra         # or jump to a model ID directly
❯ /chat                        # read-only mode (no writes/shell)
❯ /yolo                        # auto-approve all writes + shell
❯ /exit

API key failover

When the OAuth backend hits its usage limit, gptcode automatically falls back to an API key. Set it once:

# Windows cmd
set OPENAI_API_KEY=sk-...
# PowerShell
$env:OPENAI_API_KEY="sk-..."
# or write to ~/.gptcode/api-key (never commit this file)

Semantic context (optional)

Embeddings require a free Cloudflare Workers AI account:

# PowerShell
$env:CF_ACCOUNT_ID="your-account-id"
$env:CF_AI_TOKEN="your-api-token"

gptcode silently skips embedding if these are absent.

Behavior

| Area | Behavior | |------|----------| | Auth | ChatGPT OAuth primary (~/.codex/auth.json); consent in ~/.gptcode/ | | Failover | On OAuth usage limit → API key + notice; gptcode status shows reset time best-effort | | Tools | Files, content search, shell; workspace trust auto-allows project edits; shell prompts unless /yolo | | Agent | Multi-step loop + verify-before-done gate; ask_user for HITL checks | | Guidance | GPTCODE.md → else AGENTS.md / CLAUDE.md | | Sessions | Stored under ~/.gptcode/sessions/; --continue / --resume | | Models | See below | | Telemetry | None | | License | Apache-2.0 |

Models

OAuth backend model IDs (these are real Codex model identifiers, not placeholders):

| ID | Notes | |----|-------| | gpt-5.6-luna | Default — fastest | | gpt-5.6-terra | Balanced | | gpt-5.6-sol | Most capable | | gpt-5.5 | Prior generation |

Use /model inside the session to switch. Available models depend on your account tier; if a model ID returns an error, switch to another via /model.

API-key backend uses the standard OpenAI model list (gpt-4.1-mini, gpt-4.1, etc.).

Auth + model transport

Follows EvanZhouDev/openai-oauth v2:

| Piece | Package / flow | |-------|----------------| | Login | Browser OAuth → ~/.codex/auth.json (same as npx openai-oauth login / Codex) | | Credentials | @openai-oauth/local → openaiCredentials({ authFilePath }) | | OAuth models | @openai-oauth/ai-sdk → createOpenAIOAuth(credentials) + Vercel AI SDK streamText | | API failover | @ai-sdk/openai with your OPENAI_API_KEY / ~/.gptcode/api-key |

OAuth transport stability: the ChatGPT account API is unofficial and may change without notice. If the OAuth path stops working, set OPENAI_API_KEY and gptcode will use the stable OpenAI API automatically.

Offline / CI mocks

# Windows cmd
set GPTCODE_MOCK_AUTH=1
set GPTCODE_MOCK_MODEL=1
# PowerShell
$env:GPTCODE_MOCK_AUTH="1"
$env:GPTCODE_MOCK_MODEL="1"

Local development

git clone <repo>
cd chatgpt-cli
npm install
npm run build        # compiles src/ → dist/
npm test             # build + 103 unit tests
npm run smoke        # build + CLI binary smoke test
npm run dev          # run via tsx (no build step)
npm run link:global  # npm link — puts gptcode on PATH from dist/

Publish

npm run build && npm test       # prepublishOnly runs this automatically
npm publish --access public     # or: npm publish (unscoped)

Checklist before publishing:

• [x] bin: { "gptcode": "./dist/cli.js" } in package.json
• [x] files: ["dist", "LICENSE", "README.md"]
• [x] engines: { "node": ">=20" }
• [x] prepublishOnly runs build + test
• [x] Disclaimer and no-telemetry statement in README
• [x] LICENSE is Apache-2.0
• [ ] npm name gptcode available — confirm with npm view gptcode before publishing
• [ ] Live OAuth smoke test completed on target OS (issue 0015)

License

Apache-2.0