Granular docs

Start here

Getting started

New to Granular? Install it on your Mac or Windows PC, plug in an AI subscription you already have, and run your first session. These pages also map the window, so you know where everything is.

• What is Granular?Granular is a desktop app for Mac and Windows where an AI agent builds and runs tasks on your computer, using the Claude or ChatGPT plan you already pay for.
• Install Granular on macOSHow to install Granular on a Mac. Download the .dmg, drag the app to Applications and open it. It's free, notarized by Apple, and needs no account.
• Install Granular on Windows (beta)How to install Granular on Windows 10 or 11: download the installer, click past the one-time SmartScreen warning, and open it from the Start menu.
• Windows betaGranular on Windows works like the Mac version, with a few differences: Ctrl shortcuts, a PowerShell terminal, click-to-update and a one-time security warning.
• Your first sessionHow to get started with Granular: set it up, pick a project folder, connect an AI model and give the agent its first task, then watch it work.
• The Granular windowA map of the Granular window: the chat, your projects and sessions, the Preview, Files, Brain and Terminal tools, settings, quick actions and shortcuts.
• Use your existing AI subscriptionsUse the Claude or ChatGPT subscription you already pay for in Granular, or your own API keys or OpenRouter. No new AI plan needed, and you can mix them freely.
• What's new in 0.6.0Granular 0.6.0 adds the Preview canvas, comments on pages, five new coding agents, OpenRouter sign-in, local models, Settings → AI accounts and model pins, plus fixes for Windows and workers.

Core concepts

The building blocks behind every project: sessions and projects, the Files, Terminal and Preview tools beside every chat (with the Preview canvas and comments), a boss that hands work to worker agents, branch sessions for safe changes, the digital brain that remembers each project, the roadmap board, the resource library, the Vault for your keys, and what Granular can see and change on your computer.

• Sessions and projectsA project is a folder on your computer and a session is one AI agent conversation working in it. How to create, switch and close them, and run several at once.
• FilesBrowse every file your AI agent creates, read and edit Markdown notes as they update live, and add files to the chat, all in Granular's built-in Files tool.
• Tool tabsKeep several web pages, files and terminals open in one chat with tabs in Preview, Files and Terminal. How to open, switch and close tabs, and why some pause.
• The Preview canvasSee every page, image, video and PDF you're working on side by side on one zoomable board in Preview. Check pages at desktop, tablet and phone size, save pictures, and point your agent at any frame.
• Preview commentsPin feedback straight onto a page in Preview, collect it in one panel, and send it all to the chat as one batch, with a screenshot of each spot.
• TerminalWatch every command your AI agent runs in Granular's built-in terminal, type your own, or open more terminal tabs, each on the main project or a branch copy.
• Boss and worker agentsRun several AI agents in parallel: make one session the boss and it hands tasks to worker agents, collects their reports and merges their work back.
• Branch sessionsLet an AI agent work on its own git branch in a copy (a worktree) of your project, so its changes stay apart until you merge them. No git skills needed.
• Digital brainGive your AI agent a memory of your project: a digital brain is a folder of linked notes on your goals and decisions that every agent reads before it starts.
• Roadmap boardA kanban roadmap you share with your AI agents: six columns, cards with a priority, and one click to hand a card to an agent, which moves it as it works.
• Resource library and skillsInstall agent skills, starter kits, design packs and prompts from Granular's Library, including skills from GitHub, and share your own on the Marketplace.
• Vault for API keys and secretsWhere to store API keys for an AI agent: the Vault keeps secrets encrypted on your computer and passes them to sessions by name, so a key never shows in chat.
• Privacy and accessControl what an AI agent can touch: give it extra folders to edit or only read, and choose whether it asks before changing files or running commands.

Guides

Step-by-step guides for the things you do most: put an AI model behind a session (Claude, Codex, Gemini, the AI Add-on or your own provider), add files to a chat, build and publish a landing page, get short TL;DR answers, and talk to Granular with your voice.

• Connect an AI modelAll the ways to connect an AI model to Granular: sign in with Claude or Codex, plug in a coding agent like Cursor or GitHub Copilot, add a key, sign in to OpenRouter, run local models, or use the AI Add-on.
• Manage your AI accountsSettings → AI accounts shows every AI account Granular can use, how each connects, what it costs and whether it works. Check it, sign in again, set a project default, hide or remove it.
• Connect CodexUse OpenAI Codex in a desktop app without the terminal: sign in with your ChatGPT plan (the free plan works) or add an OpenAI API key. Granular can even install Codex for you.
• Connect GeminiHow to use Google Gemini in Granular: create a Gemini API key in Google AI Studio, add it in the connection menu, then pick from 12 Gemini and Gemma models.
• Connect other AI providersUse DeepSeek, Kimi, GLM, Grok, Groq, Mistral, OpenRouter and more in Granular. Pick the provider, paste your API key, and Granular fills in the models.
• Sign in with OpenRouterConnect OpenRouter to Granular in one click. Approve in your browser and hundreds of models appear in the model menu, with no API key to copy or paste.
• Pick and pin modelsChoose the AI model for a chat from the model button under the message box. Search every account, read the badges, and pin favourites with Cmd+D or Ctrl+D.
• Connect OpenCodeUse your own OpenCode agent as a Granular chat engine. Install it in one click, connect a provider such as OpenRouter or Anthropic (or reuse one you added in Granular), then pick its models.
• Connect PiUse the Pi coding agent as a Granular chat engine. Install it in one click, then reuse a provider you added in Granular or connect OpenRouter, Anthropic, OpenAI or xAI with /login.
• Connect CursorUse your Cursor account as a Granular chat engine through the Cursor CLI. Install it in one click, sign in with your Cursor account, and pick from Cursor's models.
• Connect GrokUse Grok in Granular through xAI's official Grok CLI. Install it in one click, sign in with your Grok account (sign-ins last 7 days) or use an xAI key, then pick a model.
• Use GitHub CopilotUse your GitHub Copilot plan in Granular through GitHub's official Copilot CLI. Install it in one click, sign in with GitHub, and pick Auto or a model.
• Add a custom AI providerUse OpenRouter, a local model in Ollama or LM Studio, or any OpenAI- or Anthropic-compatible AI service in Granular with a web address, key and model names.
• Local models (Ollama, LM Studio)Run AI models on your own computer with Ollama or LM Studio. Granular finds them when the model menu opens, with no key and no cost per message.
• Granular Hosted modelsUse Claude, GPT, Gemini and more in Granular with no AI subscription or API key: the AI Add-on gives you hosted models paid for with credits.
• Add files to a chatHow to give an AI agent the exact files and folders to work on: add them to your message from Files or Brain, drag them in, or attach a file from your computer.
• Build a landing pageBuild a landing page with AI and no coding: describe it in the chat, watch it appear in the preview, change it by chatting, then share it with one click.
• TL;DR modeMake long AI agent replies easy to skim: TL;DR mode ends each one with a short summary and folds the full answer just above it, ready to open whenever you want.
• Voice dictation and voice modeTalk to your AI agent instead of typing. Granular turns speech into text privately on your computer, and voice mode (beta) reads replies aloud, hands-free.

Connectors

Plug in the apps you use, like Gmail, Slack, Notion and more than 1,400 others, and your agents can read and act in them from any chat. Choose what agents may do in each app, connect several accounts, and bring in tools from Claude, Codex, Gemini or your own servers.

• ConnectorsLet your AI agent use Gmail, Slack, Notion, Stripe and more, plus your own MCP servers. Connect each once and every Claude, Codex or Gemini chat can use it.
• Connect an appHow to connect Gmail, Slack, HubSpot and over 1,400 other apps to your AI agent in Granular, so it can read, write and act in them, with you in control.
• App permissionsStop an AI agent from sending, changing or deleting things in your apps: set each app to Read only, Read & write or Everything, and approve sends in chat.
• Connector accountsConnect two accounts of the same app, like work and personal Gmail, and tell the AI agent which to use with @. How to name, limit and switch each one.
• Connectors in chatUse your connected apps in any chat: switch them on from the + menu, point the AI agent at one app or account with @, and see every action it takes in the chat.
• Built-in connectorsConnect Notion, GitHub, Linear, Slack, Stripe, Vercel and more to your AI agent with Granular's built-in connectors: sign in once or paste a token.
• This computer connectorsUse the connectors and MCP servers you already set up in Claude, Claude Code, Codex or Gemini. Granular finds them, and you choose which chats get them.
• Bridge to every modelUse Claude-only connectors, such as your claude.ai Gmail, from a Codex or Gemini chat: your own Claude does the task, read-only unless you allow actions.
• Custom connectorsHow to add any MCP server to Granular: a program on your computer, or a remote server with a token or browser sign-in. It works with Claude, Codex and Gemini.

Account & billing

Your Granular account, the Pro plan and the AI Add-on: what each costs, how credits work, using Pro on more than one computer, moving a purchase between accounts, and the links you publish.

• Account and sign-inDo you need a Granular account? It's optional. Sign in with an emailed code, no password, and your plan, AI credits and links follow you to any computer.
• Plans and pricingGranular pricing: free to use with your own AI, Pro from $12.99 a month (or $259 for Lifetime) to lift limits, and an optional AI Add-on from $20 a month.
• Billing FAQQuick answers to Granular billing questions: Pro vs the AI Add-on, prices, switching plans, Lifetime, credit packs, invoices, cancelling and the 30-day refund.
• AI Add-on creditsHow Granular AI credits work: AI Add-on tiers from $20 a month, credit packs that never expire, which credits go first, and what happens when they run out.
• Pro on multiple computersHow many computers can use Granular Pro? Two at once, including Lifetime. How to add a computer, move Pro to a new one, or handle a lost laptop.
• Move a purchase to another accountGranular purchase on the wrong account? A purchase stays with the account that adds it first and can't be moved in the app. How to avoid it, and get help.
• Published linksShare what your AI agent built: publish a page or note to a web link, or share something running on your computer with a live link for up to 4 hours.

Help & reference

Keep Granular quick with many sessions open, and the network addresses to allow if you work behind a company firewall.

• Keeping Granular fastWhy Granular gets slow after days open or with many sessions, and three quick fixes: restart it, close sessions you aren't using, and start big jobs fresh.
• Network and firewall allowlistGranular blocked on a work or school network? The domains and hosts to allowlist for sign-in, checkout, updates and publishing, ready to give your IT team.