GranularSessions and projects
A 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.
Updated 2026-10-20
A project is a folder on your computer. A session is one conversation with an AI agent, with its own terminal, working inside that folder. One project can hold several sessions at once, and each one keeps its own conversation.
A few words you'll see:
- Folder: a place on your computer that holds files, like the ones you see in Finder on a Mac or File Explorer on Windows.
- Terminal: a text window where commands run. Each session has one, and the agent types into it so you can watch what it does. Open it with the Terminal icon in the title bar. You never have to type there yourself. See Terminal.
- Agent: the AI you chat with. It reads and writes files in the project's folder and runs commands in the terminal.
Where to find them
The left side of the Granular window has two columns:
- The project rail (the narrow strip of square tiles). Each tile is one project. The + tile under them is New project….
- The sessions sidebar (next to it). At the top is the project's name, with its folder underneath. Below that are the New session button, your open sessions, and a Previous section for sessions you've closed.
Each session shows a small status label:
| Label | What it means |
|---|---|
| New | Created, no task given yet |
| Working | The agent is working now |
| Needs you | Waiting on your decision, for example an approval |
| Ready | Finished, ready for you to look at |
Projects
Create a project from a folder
- Click the + tile at the bottom of the project rail (New project…).
- In the window titled Choose a folder, pick a folder. This can be a folder you already have, such as a website you're working on. To start from nothing, use the window's new folder button, name the folder, and pick it.
- Confirm your choice (on a Mac the button says Open).
The project appears in the rail, named after the folder, and opens with a first session ready to use. Granular doesn't move or copy your files. The project simply points at that folder.
Switch projects
Click a project's tile in the rail. Each project remembers which of its sessions you were last in. Sessions in other projects keep running while you're away, and a project's tile glows when one of its sessions is working.
To change the order of the tiles, drag them up or down.
Change a project's settings
Click the ⋮ button at the top of the sessions sidebar (Project settings). You can change:
- Name: what the project is called in Granular. The folder on your computer keeps its name.
- Home folder: click Change… to point the project at another folder. New sessions start there. Sessions already open keep their current folders, and no files move.
- Default account for new sessions: which AI account every new session in this project starts on. Choose No default and Granular picks a signed-in account that's working. You can still switch account inside any session.
- Icon: a background colour and symbol, or your own image with Choose image….
Click Save when you're done.
Remove a project
- Open Project settings.
- Click Remove this project…, then Click again to remove this project.
This closes the project's open sessions and deletes its Previous history from Granular. The folder and every file in it stay on your computer. To use the folder again, create a new project from it. If you remove your last project, Granular asks you to choose a folder to work in.
Sessions
Start a session
Click New session at the top of the sessions sidebar, or press ⌘T on a Mac (Ctrl+T on Windows).
The new session is called "Session 1", "Session 2" and so on, and it starts in the project's folder. Type what you want in the chat box at the bottom.
To start a session in a different folder from the project's, open the command palette (⌘K on a Mac, Ctrl+K on Windows), choose New session in folder…, and pick the folder. The session still belongs to the current project.
To start a session on its own copy of the project, see Branch sessions.
Rename a session
Any of these works:
- Double-click the session's name in the sidebar.
- Click the session, then press F2.
- Hover the session, click ··· (Session options), then Rename.
- Open the command palette and choose Rename session.
Type the new name and press Enter. Press Esc to cancel.
Switch between sessions
Click a session in the sidebar. The first nine sessions in a project also have shortcuts: ⌘1 to ⌘9 on a Mac, Ctrl+1 to Ctrl+9 on Windows. The shortcut shows at the right of each row.
Switching doesn't pause anything. A session you leave keeps working in the background, and its status label tells you when it's Ready or Needs you.
How many sessions can run at once
| Free | Pro | |
|---|---|---|
| Projects | 2 | No limit |
| Open sessions in each project | 4 | No limit |
Only open sessions count. Closed sessions in Previous don't. If you're at the limit, Granular asks you to upgrade to Pro when you try to add one more; close a session you've finished with to make room instead. See Plans and pricing.
Several sessions working at the same time use more of your computer and of your AI account's usage. If Granular feels slow, see Keeping Granular fast.
Close a session
- Hover the session and click ··· (Session options).
- Click Close session.
You can also open the command palette and choose Close session to close the one you're in.
If nothing is running, the session closes straight away.
If something is still running, Granular asks first: Close this chat? It names what's running, for example the agent's turn, a command such as npm run build, or a program in one of its terminals. Then:
- Cancel (the default) leaves everything as it was.
- Stop and close stops what's running and closes the session. Anything the agent hadn't saved into your folder yet is lost.
If one of the session's terminals has its own copy with changes not yet merged, the pop-up says so too. Closing never throws that work away: the copy stays on your computer, on its own branch.
What happens when you close a session
Closing a session ends it for good:
- All its terminals shut down and the agent stops.
- The conversation is saved as a read-only record under Previous at the bottom of the sidebar.
- You can't reopen or continue it. To carry on the same work, start a new session and tell the agent what you were doing. It can read the files in the folder, which are all still there.
- Files the agent created or changed stay in the folder. Closing a session never deletes files.
If you close the last open session in a project, Granular opens a fresh one, so a project always has at least one.
Read an old session
- At the bottom of the sessions sidebar, click Previous to expand it. The number next to it is how many closed sessions there are.
- Click a session. Hover it first to see the first thing you asked it.
A window opens with the session's name, when it was closed ("Concluded … · read-only"), and the whole conversation, including the commands the agent ran and what they printed. Press Esc or click esc to close it.
The list shows your 50 most recent closed sessions, newest first.
What happens when you quit Granular
Quitting is not the same as closing. When you open Granular again:
- Your open sessions come back in every project, with their names and conversations.
- The agent remembers the conversation and can carry on from it.
- Each session's Main terminal starts fresh, and extra terminal tabs don't come back. Anything that was running, such as a preview server, has stopped and needs starting again. Ask the agent to do it.
- Your Preview and Files tabs come back.
If an agent is working when you quit, Granular warns you first: "An agent is still working" (or how many are), with the session names. Quitting now stops them straight away, and work not yet saved into your folder is lost.
- Click Keep working to cancel the quit. Wait until each session shows Ready, then quit.
- Click Quit anyway to quit now.
Long conversations
Every AI model can only keep a certain amount of conversation in mind at once. When a session's chat gets very long, Granular summarizes the earlier part so the agent can keep going without losing the thread. This is called compacting.
When it happens you'll see a thin line marked compacted in the chat. Everything above the line stays on screen and saved. The agent carries on from the summary.
- To compact yourself at any time, type /compact in the chat box and send it.
- To turn automatic compacting off, open Settings → General, and under Conversations switch off Auto-compact long conversations. It's on by default.
The AI model can also shorten its own memory in the middle of a task. When it does, it may add a short grey line saying so, and pause briefly while it does it.
Troubleshooting
If you see the upgrade window when you click New session or +, you're at the Free limit (4 open sessions in a project, or 2 projects). Close a session you've finished with, or remove a project you no longer use. Or upgrade to Pro.
If you see "Close this chat?", something is still running in the session. Click Cancel and wait until the session shows Ready, or click Stop and close to stop it and close anyway.
If you see "That folder does not exist." when creating a project, the folder was moved, renamed or deleted after you chose it. Click + again and choose it from where it is now.
If a session you closed is missing from the sidebar, that's expected. Look under Previous at the bottom of the sidebar. Previous only appears once a project has at least one closed session.
If a session came back after a restart but a preview or server isn't running, the terminal started fresh when you reopened Granular. Ask the agent to start it again.
If a project moved folders on your computer, open Project settings, click Change… next to Home folder, and choose the folder's new location. Then start a new session.