Connect Codex

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

• Sign in with your ChatGPT plan. The recommended route. Every ChatGPT plan includes Codex, even the free one (with usage limits; paid plans get more).
• Add an OpenAI API key. You pay OpenAI for what you use.
• Run the Codex CLI yourself. For the curious. Granular uses whatever account the CLI is signed in to.

No Codex at all? The AI Add-on gives you hosted models with no setup. See the last section.

First: install Codex

Every route uses OpenAI's official Codex command-line tool (CLI) behind the scenes, so it needs to be on your computer once. Unlike Claude, it doesn't come built into Granular. It's free.

You don't have to install it ahead of time. If Codex is missing when you click Codex under Add your AI agent, the connection menu shows a small panel titled Codex needs a one-time install:

1. Click Install for me. Granular types the install command into this chat's terminal. You can watch it run in the Terminal tool.
2. Wait. Granular checks every few seconds. As soon as it finds Codex, it carries straight on to the sign-in.

The panel also has:

• The install command, with a Copy button, if you'd rather run it yourself.
• I've installed it - check again, for when you installed it another way.
• A link to OpenAI's Codex guide.

Which command it uses depends on your computer:

(Node.js is a free tool that many command-line programs need. You can get it from nodejs.org.)

On a Mac without Node.js, Install for me is greyed out and the panel offers a Get Node.js link. Install Node.js first, or get OpenAI's Codex app, which includes the Codex CLI.

Option 1: Sign in with your ChatGPT plan (recommended)

Codex use comes out of your ChatGPT plan, with no separate bill.

1. Click the connection menu (the button under the message box that shows your current connection's name, or Connect an agent), then Add your AI agent.
2. Under Subscriptions, click Codex (its tag says Sign in).
3. A card appears with a link and a one-time code, much like signing in to a smart TV.
4. Open the link on any device (your phone works fine), enter the code and approve.
5. The card finishes by itself and the account appears with its email.

Because it uses a link and code instead of opening a browser on your computer, this works even on locked-down work machines.

During first-run setup, the ChatGPT (Codex) card does the same thing.

Option 2: Add an OpenAI API key

Connect Codex with an OpenAI API key and pay OpenAI for what you use instead.

1. Create a key at platform.openai.com/api-keys.
2. In the connection menu, click Add your AI agent. Under Keys & providers, click API key, then OpenAI, and paste it.
3. The account shows only the last four characters. The key itself is never shown again.

Worth knowing: these accounts power Granular's own agents. Keys your projects need (a payment service key for your website, say) belong in the Key Vault instead.

Option 3: Run the Codex CLI yourself

Granular is a real terminal, so you can always use Codex's own commands in any session terminal. Granular adopts whatever account the CLI is signed in to.

Your Codex sign-in is saved by the CLI on your own computer and nowhere else.

Pick a model and look for the check mark

With Codex connected, the model button under the message box lists the models your Codex account can use. Switch for each message, like any engine.

On a ChatGPT sign-in, the API-key-only models show greyed out with the reason. The thinking control beside the model button offers Low, Medium, High and X-High.

Under each Codex reply, the footer names the model that actually answered, which can differ from the one you picked if Codex switched it for that turn.

Granular only shows a ✓ after the account's name once a real, tiny test (or a real message) has worked through it, because being signed in isn't the same as being able to do work. Point at the ✓ and the tooltip says Verified. To run that check yourself, use Verify connection on the account's ⋯ menu, or on its card in Settings → AI accounts.

Your Codex chats stay in Granular

New Granular chats on Codex are kept out of the Codex app's and the Codex CLI's own history, so your Granular work doesn't fill up your Codex app. Granular keeps its own copy of every chat. If you restart Granular, the chat carries on with a summary of what came before.

Conversations you already have in the Codex app aren't touched.

While Codex works, its tool activity (reading files, running commands) is grouped into one tools row you can open, with a red count if any step failed.

Switching accounts safely

OpenAI allows one active Codex sign-in per computer: signing in again replaces the previous one. So Granular keeps exactly one Codex account. Once you're signed in, the Codex row under Add your AI agent has the tag Switch ("Replaces your current Codex account"). It signs out the current account, then shows a new link and code for the next one.

The switch is built to cost nothing if it doesn't finish. Granular saves your current sign-in first, and if the new one stalls, is cancelled or the code expires, your previous account comes back automatically, even if you quit the app mid-switch.

If a sign-in stops working, click Reconnect Codex on the chat message, or Sign in again on the Codex card in Settings → AI accounts. That also uses a link and code. If it doesn't finish within about three minutes, the card stops waiting, shows what Codex said, and offers Retry.

To stop seeing Codex in the account list without signing out, click Hide from picker on its card in Settings → AI accounts. See Manage your AI accounts.

No Codex? Use the AI Add-on

You don't need a Codex account, or any AI account, to use Granular. The AI Add-on (Granular Hosted) gives you hosted models with no setup, on any plan. It works happily alongside a Codex account you add later. See Connect an AI model and Granular Hosted models.

Limits

• One Codex sign-in per computer, as above.
• Codex's "computer use" doesn't work inside Granular. OpenAI makes it work only in its own Codex app.
• Older models need an API key. See the model table.

Troubleshooting

If you see "… isn't available on this Codex account"
That model isn't offered to the account you're signed in with. Choose a model from the list that your account can use, or switch the chat to an account that supports it.

If the chat stops with "This Codex version could not keep the chat out of shared history"
Your Codex CLI is too old. Update Codex (for example, run npm i -g @openai/codex again on a Mac), then try again.

If the panel says "Install finished, but Granular can't see Codex yet"
Click I've installed it - check again. If that doesn't find it, quit Granular completely (⌘Q on a Mac; on Windows, close every Granular window) and open it again.

If the panel says "The install didn't finish"
Look in the Terminal tool for the error, then click Try again. A common cause on a Mac is a missing Node.js.

If the panel says "The install is taking a while"
Granular stops waiting after about three minutes. Check the Terminal tool. If the install did finish, click I've installed it - check again.

If Install for me is greyed out
Node.js isn't on this computer. Use the Get Node.js link, install it, then quit and reopen Granular. Or get OpenAI's Codex app, which includes Codex.

If the Codex sign-in kept spinning on Windows
This happened when your Windows user folder had a space in its name (for example C:\Users\Sam Lee). It's fixed in 0.6.0: update Granular and sign in again.

Related