Connect an AI model

Granular's agent needs an AI model to think with. You can plug in your existing AI subscriptions, like Claude and Codex, run a coding agent such as Cursor or GitHub Copilot, paste an API key, sign in to OpenRouter, use models on your own computer, or use Granular's own AI Add-on. You add and switch all of them from the connection button under the message box.

(People often call these models LLMs, short for large language models: the kind of AI behind chat assistants.)

The ways to connect

You can set up as many as you like and use a different one in each session. None of them changes what your Granular plan costs, except the AI Add-on, which is its own purchase.

An API key is a long password that lets software use your account with an AI company. You create one on the company's website.

Open the connection menu

1. Look at the row of controls just under the message box.
2. Click the button that shows your current connection's name, such as Claude, Codex or G.hosted, with a small ▾ arrow. If nothing is connected yet, it reads Connect an agent.

The menu opens above the button. At the top, under Accounts, is every account you've set up. The one this session uses has an outline. The settings icon on the Accounts title line (Manage accounts) opens Settings → AI accounts. Below the list is Add your AI agent.

Add your AI agent has three sections:

• Subscriptions: Claude and Codex.
• Coding agents: OpenCode, Pi, Cursor, Grok and GitHub Copilot.
• Keys & providers: OpenRouter, API key (which opens to Anthropic, OpenAI and Gemini) and Custom provider.

Each row has a price tag (such as Free, Plan or Pay as you go) and a tag for what clicking it does: Install, Sign in, Ready, Switch or Add. Point at a row for a one-line explanation. Once you've added Cursor, Grok, GitHub Copilot or OpenRouter, its row leaves this menu; manage it in Settings → AI accounts instead. Claude stays, so you can add another Claude account. If you don't have a paid AI Add-on, Get the AI Add-on sits at the bottom of the menu.

Add a connection

Claude

Before you start: you need a Claude Pro, Max, Team or Enterprise plan. A free Claude account won't work. Nothing to install: Claude comes built into Granular.

1. Open the connection menu and click Add your AI agent.
2. Under Subscriptions, click Claude (tag Sign in).
3. Your web browser opens on Claude's sign-in page. Sign in and approve.
4. Come back to Granular. The menu shows Signing in… and updates by itself when you finish.

Your Claude account appears under Accounts with its email, and the session switches to it. You can add more than one Claude account. If you sign in to one that's already there, Granular says You're already signed into that account. Switched to it.

Codex

Before you start: any ChatGPT plan works, including Free (with usage limits). You also need OpenAI's Codex command-line tool on your computer. If it's missing, Granular shows a panel with an Install for me button that installs it and then carries on to the sign-in.

1. Open the connection menu and click Add your AI agent.
2. Under Subscriptions, click Codex (tag Sign in).
3. Granular shows a link and a one-time code. Open the link on any device, sign in to ChatGPT and enter the code.
4. The menu updates by itself when you finish.

Codex allows one sign-in at a time. Once you're signed in, the Codex row's tag says Switch, and using it replaces the current account. See Connect Codex.

A coding agent: OpenCode, Pi, Cursor, Grok or GitHub Copilot

Under Coding agents, click the agent. Granular installs it with Install for me if it's missing, then signs you in or connects a provider. Each runs that company's own agent as the engine behind the chat, with every command it runs kept in your visible terminal. See Connect OpenCode, Connect Pi, Connect Cursor, Connect Grok and Use GitHub Copilot.

OpenRouter

Under Keys & providers, click OpenRouter (tag Sign in) and approve in your browser. Hundreds of models, no key to paste. See Sign in with OpenRouter.

An API key (Anthropic, OpenAI or Gemini)

Before you start: create a key on the company's website:

• Anthropic: console.anthropic.com. Pay as you go, billed separately from any Claude subscription.
• OpenAI: platform.openai.com. Pay as you go, billed separately from any ChatGPT subscription. Needs OpenAI's Codex tool on your computer, as above.
• Gemini: aistudio.google.com, where keys are free to create. Needs Google's Gemini command-line tool on your computer. See Connect Gemini.

1. Open the connection menu and click Add your AI agent.
2. Under Keys & providers, click API key.
3. Click Anthropic, OpenAI or Gemini.
4. Paste your key into the box.
5. Click Add.

The key appears under Accounts, shown by its last four characters. Granular runs a tiny test straight away, and a ✓ appears after the name when the key works. The key is stored encrypted on your computer and is never shown in chat.

A custom provider

1. Open the connection menu and click Add your AI agent.
2. Under Keys & providers, click Custom provider.
3. Pick your provider from the list (DeepSeek, Kimi, GLM, xAI, Groq, Mistral, OpenRouter and others) and paste your key, or choose Another provider - type its details and fill in the form. Then click Add & test.

See Connect other AI providers for the list, and Add a custom AI provider for typing the details yourself.

Models on your own computer

If Ollama or LM Studio is running, the connection menu shows On this computer with Use local models. One click, no key. See Local models (Ollama, LM Studio).

The AI Add-on (Granular Hosted)

Before you start: nothing. The AI Add-on works on any Granular plan, including Free.

• Free credits: when you first set up Granular, choose Start free on the Free credits card. This gives you a one-time bundle of credits. You need a free Granular account; no card.
• Buy it: open the connection menu and click Get the AI Add-on at the bottom, or open Settings → Billing & plan, and choose a tier. See AI Add-on credits.

Once it's active, a G.hosted row appears under Accounts. Choose it, then pick any of its models from the model button. See Granular Hosted models.

Why there is no Gemini sign-in

Google stopped letting personal Google accounts sign in to its Gemini command-line tool, on free and paid plans alike. Use a Gemini API key instead: it gives you the same models. Gemini models are also available through the AI Add-on and through providers such as OpenRouter.

Switch the connection or model for a session

Switch the connection

1. Open the connection menu.
2. Click another row under Accounts.

If the chat is empty, the session switches straight away. If it already has messages, a card asks Switch to [name]?. Switching starts a fresh conversation with the new account, because a conversation can't move between accounts. Granular gives the new agent a short summary so you can carry on. Your files, terminal and preview are untouched.

• Click Switch & hand off to switch.
• Click Cancel to stay.

If the agent is still working, the card says Finish the current turn first. Wait for it, or stop it, then switch.

Switch the model

Next to the connection button is the model button, which picks the model for your next messages. What it lists depends on the account: Claude's models for a Claude account, Codex's for Codex, the Hosted catalog for G.hosted, your models plus the provider's current list for a custom provider or OpenRouter, or the agent's own list for a coding agent. You can search it, including your other accounts, and pin favourites. See Pick and pin models. Beside it, a Claude or Codex account also shows a control for how hard the model thinks. Some Hosted models show thinking on or thinking off instead.

You can change the model between any two messages without starting over. Granular remembers your choice for that account in that project.

Each model in the list has a one-line description under its name. For a Claude account (a Claude sign-in or an Anthropic API key) the list is:

The thinking control offers Low, Medium, High (the default), X-High and Ultra. Higher levels think longer before answering. If a model doesn't support a level, it quietly uses a lower one.

For Codex models, see Connect Codex. For Gemini models, see Connect Gemini.

Set a default for a project

To start every new session in a project on the same account:

1. Open Settings → AI accounts.
2. On the account's card, click Set as default and choose the project.

The card then shows Default for and the project's name. Click Default to clear it. Worker agents always use their boss's account. See Manage your AI accounts.

Remove or hide a connection

Open the connection menu, point at the row, click the ⋯ that appears, then Remove. It happens straight away, with no confirmation. Any session using it moves to another of your accounts.

Accounts that come from an app signed in on your computer, such as the Claude sign-in Granular picked up when you first set it up, or Codex, Cursor and GitHub Copilot logins, have no Remove. Choose Hide from picker in the same ⋯ menu instead: Granular stops showing and using it, and the login on your computer is untouched.

What happens if a connection stops working

• A ✓ or ! after an account's name. ✓ means a test or a real message worked. ! means Granular has found it can't work as set up; point at it to read why.
• Check it. Point at the row, click ⋯, then Verify connection. Granular sends a tiny test message. Settings → AI accounts shows the result on the account's card.
• Claude sign-in expired. Click Re-sign in to Claude on the chat message, or point at the row, click ⋯, then Sign in again, and finish in your browser. If Claude was signed out on this computer, the connection button reads Claude · signed out and the menu offers Sign in again.
• Codex sign-in ended. Click Reconnect Codex on the chat message, or Sign in again on the Codex card in Settings → AI accounts.
• An account you removed. Sessions that used it move to another of your accounts on their own.
• A card in the chat. When a message fails, the chat shows a card naming the cause and a way out, such as Pick another model, Open the model picker or a link to check your usage.
• AI Add-on credits run out. The chat shows a card with Get the AI Add-on, a way to add a credit pack, and a way to connect your own AI. Your sessions, files and chat history are kept.

Troubleshooting

If the connection button reads "Connect an agent"
Nothing is connected yet. Click it and add a connection as described above.

If the connection button reads "Claude · signed out"
Your Claude sign-in on this computer ended. Click the button, then Sign in again, or pick another account.

If you see "This computer's saved Claude sign-in was rejected"
Open the connection menu, point at your Claude row, click ⋯, then Sign in again. Or pick another account, such as G.hosted.

If you see "Your Claude login expired or was revoked"
Click Re-sign in to Claude under the message and finish in your browser, or use ⋯ then Sign in again in the connection menu.

If you see "Your API key was rejected"
The key is wrong, deleted or out of credit. Create a new key on the company's website, add it under API key, and remove the old one.

If you see "The API key for … couldn't be read"
Add the key again under API key, or pick another account.

If a Codex error in the chat shows "Reconnect Codex", or the ! next to Codex says "This ChatGPT sign-in was revoked"
Codex allows one live sign-in per account, so signing in somewhere else can end this one. Click Reconnect Codex under the message, or sign in again from Settings → AI accounts.

If you see "You have run out of tokens with …"
That company says your account has no credit left. Click the button on the card to check your usage, add credit there, or switch to another account.

If you see "Your AI credits are used up."
Your AI Add-on credits are spent. Use Go to billing or Buy a credit pack, or switch to your own account.

If you see "… isn't available on this account - using …"
The model you used before isn't offered on this account, so Granular picked the default. Choose another model from the model button.

If you see "Granular could not reach …"
Your computer seems to be offline, or a network is blocking the service. Check your connection and send again. See Network and firewall allowlist.

If you see "Finish the current turn first."
You tried to switch accounts while the agent was working. Wait for it to finish or stop it, then switch.

If an account is missing from the list
It may be hidden. Open Settings → AI accounts, open Hidden, and click Show.

If clicking Codex shows "Codex needs a one-time install"
OpenAI's Codex tool isn't on this computer yet. Click Install for me, or follow the steps in Connect Codex.

For custom provider messages, see Add a custom AI provider.

Related