Documentation
Everything you need to build with Granular
Plain-English guides for the terminal for everybody — from your first session to running agents in parallel.
Getting started
Install Granular and run your first AI agent session in minutes.
What is Granular?
Granular is a macOS app that turns the terminal into a place anyone can use. You chat in plain English and AI agents do real work — design, build, publish, and ship — in real terminals you can watch.
Read →
Install on macOS
Download and install Granular for macOS in three steps: get the .dmg, drag the app to Applications, and open it. Free to start.
Read →
Your first session
Start a session, chat your goal in plain English, and watch an AI agent do the work in a real terminal. Here is exactly what to expect the first time.
Read →
The interface
Granular has four core surfaces — chat, terminal, preview, and docs. Here is what each one does and when to use it.
Read →
Core concepts
The ideas that make Granular work — sessions, agents, the Vault, your brain.
Sessions & projects
A session is one chat-plus-terminal workspace; a project groups related sessions and files. Here is how they fit together.
Read →
Boss & worker agents
In Granular you can promote a session to a boss that delegates tasks to worker agents running in parallel, each in its own isolated copy of the project.
Read →
The Vault (secrets)
The Vault is Granular’s built-in encrypted store for API keys and secrets. Enabled entries are injected into your terminal as environment variables and never printed in chat.
Read →
Digital brain & roadmap
A digital brain is a folder of linked markdown notes that gives your agents standing context — your mission, projects, and decisions — plus a roadmap board they can read and update.
Read →
Resource library & skills
The resource library is where reusable capabilities live — skills, templates, brains, and design packs you can install into a project with one click.
Read →
Branch sessions (git)
Branch sessions let you try work in an isolated copy of your project using git worktrees, so experiments never disturb your main copy until you choose to merge.
Read →
Guides
Step-by-step playbooks for getting real work done from the terminal.
Connect an LLM
Use your own Claude or Codex login, or add the Granular AI add-on for hosted models with no setup. Here is how to choose and switch models.
Read →
Build a landing page
Go from a sentence to a published landing page in Granular: describe it, preview it live, refine in plain English, and publish — no code required.
Read →
Connect tools (MCP)
MCP connectors let Granular agents work with outside tools and services — like Notion, Google Drive, and more — so they can act across your stack.
Read →
Integrate Codex
Connect OpenAI’s Codex to Granular every way it works: sign in with ChatGPT (a link and one-time code), add an OpenAI API key, or drive the Codex CLI yourself, plus models, billing, and safe account switching.
Read →
Connect Gemini
Connect Google Gemini to Granular with a Vault-injected API key, and understand why Gemini CLI chat login is separate from reliable agent automation.
Read →
Granular Hosted & credits
Claude, GPT, Gemini and more inside Granular with no AI subscription and no API keys. How credits are metered, what happens when they run out, and how to switch back to your own model.
Read →
Bring your own endpoint
Connect an Anthropic-compatible endpoint like OpenRouter with a base URL and your own API key. Stack up to 20 models behind one connection and switch per message — free on every plan.
Read →
Help & reference
Troubleshooting and reference for running Granular anywhere.