Integrate Codex: ChatGPT sign-in, API key & CLI

What connecting Codex gives you

Codex is OpenAI’s coding agent, and once connected it becomes a full engine inside Granular: your sessions can run on GPT‑5 and GPT‑5 Codex instead of (or alongside) Claude. There are three ways in, and they all end at the same place: a Codex connection in the connector menu, ready to pick for any session.

• Sign in with ChatGPT: the recommended route. Uses your existing ChatGPT plan; no keys to manage.
• Add an OpenAI API key: no ChatGPT plan needed; you pay OpenAI per use.
• Drive the Codex CLI yourself: for the terminal-curious; Granular adopts whatever the CLI is signed into.

No Codex at all? Granular’s AI add-on gives you hosted models with zero setup. See the last section.

First: install the Codex CLI

Every route drives the official Codex CLI under the hood, so it needs to exist on your Mac once:

npm i -g @openai/codex

That’s the standard install (it needs Node). Codex also ships with OpenAI’s Codex desktop app; either works. Granular finds the CLI in the usual places (Homebrew, ~/.local/bin, /usr/local/bin), and if it’s missing, the connector shows this exact command with a copy button instead of a dead end.

Option 1: Sign in with ChatGPT (recommended)

If you have a paid ChatGPT plan (Plus or Pro), this is the simplest route: Codex usage rides your subscription, with no separate bill.

• Click the connector pill (top-left of the chat) → Add your AI agent → Sign in with Codex.
• A card fills in with a link and a one-time code, the same pairing model as signing into a smart TV.
• Open the link on any device (your phone works fine), enter the code, and approve.
• The card completes by itself and the connection appears with your account email.

Because it’s a link + code rather than a browser hand-off on the Mac, this works even on locked-down setups where auto-opened browser logins break.

Option 2: Add an OpenAI API key

No ChatGPT plan? Connect Codex with a plain OpenAI API key and pay per use on your OpenAI account instead:

• Create a key at platform.openai.com/api-keys.
• In the connector pill: Add your AI agent → Add by API key → OpenAI API key, and paste it.
• The connection shows a masked label (last four characters); the key itself is never displayed again.

One distinction worth knowing: connections power Granular’s own agents. Keys that your projects need (a Stripe key for your site, say) belong in the Vault instead.

Option 3: Drive the Codex CLI yourself

Granular is a real terminal, so the power route is always open: run Codex’s own commands in any session terminal, and Granular adopts whatever login the CLI holds as the machine’s default connection.

codex login                 # browser sign-in
codex login --device-auth   # link + one-time code (what Granular uses)
codex login status          # who’s signed in right now
codex logout                # sign out on this Mac

You can even type a bare codex in a session terminal to launch the agent right there; Granular notices and works around it instead of fighting it. Credentials live in the CLI’s own file at ~/.codex/auth.json, on your Mac and nowhere else.

Pick a model and trust the Verified mark

With Codex connected, the model pill under the prompt offers its lineup: Codex default (the conversation keeps its model until you choose), GPT‑5 Codex (Codex-tuned, best for coding), and GPT‑5 (general purpose). Switch per turn, like any engine.

Granular also verifies connections honestly: signed in and can actually run work are not the same thing (a ChatGPT login without a paid plan signs in fine but can’t run turns). So Granular earns the Verified mark by running one real, cheapest-possible turn through the connection. If that answers, you know the whole path works before you trust a session to it.

Switching accounts safely

OpenAI allows one active Codex login per machine: a fresh sign-in of the same account revokes the previous token. So Granular keeps exactly one Codex connection and gives you Switch Codex account instead of a second sign-in: it signs the current account out, then shows a new link + code for the next one.

The switch is built to cost nothing if it doesn’t finish. Granular snapshots your credentials before the sign-out, and if the new sign-in stalls, is cancelled, or the code expires, your previous account is restored automatically, even after quitting the app mid-switch. And if a login ever dies (a revoked token, say), the connection offers a one-click Re-sign in that fixes it in place.

No Codex? Use the AI add-on

You don’t need a Codex account (or any account) to power Granular: the AI add-on provides hosted models: metered, zero setup, on any plan. It’s the fastest start, and it coexists happily with a Codex connection you add later. See Connect an LLM and plans.

Related