Branch sessions

A branch session works in its own copy of your project, so its changes don't touch the main copy. When you're happy with the work, you merge it back in. To start one, open the command palette with ⌘K (Ctrl+K on Windows) and choose New session on a branch….

Three words, in plain English:

• Git: a tool that keeps a history of every saved change to the files in a folder, so you can see what changed and go back. A folder that uses git is called a git repository.
• Commit: one saved checkpoint in that history.
• Branch: a separate line of work that starts from the main copy. Changes on a branch stay separate until they're merged (copied back) into the main copy, usually called main.

Granular makes the branch copy for you. You don't need to know any git commands.

Why use a branch session

• Try something without risk. A redesign, a big change, an experiment. If it doesn't work out, the main copy was never touched.
• Run sessions side by side without collisions. Two sessions in the same folder can overwrite each other's changes to the same file. Each branch session has its own folder, so they can't.
• Review before anything changes. Nothing reaches the main copy until you merge, and the agent tells you which files the merge brings in.

This is also how boss and worker agents keep workers out of each other's way: a worker started In a new worktree is a branch session.

Before you start

• The project's folder must be a git repository with at least one commit. Many code projects already are. If yours isn't, see If the project isn't a git repository.
• Git must be installed. On a Mac it comes with Apple's command line developer tools. On Windows, install the free Git for Windows from git-scm.com/download/win, then reopen Granular.
• On the Free plan, a branch session counts as one of the 4 open sessions a project can have.

Start a branch session

1. Open the project you want to branch.
2. Open the command palette: ⌘K on a Mac, Ctrl+K on Windows.
3. Choose New session on a branch….
4. Type a name for the branch, for example new-homepage. Names can use letters, numbers, dots, dashes and slashes, with no spaces.
5. Click Create branch session (or press Enter).

Other ways to get one

• Move a session you're already in onto a new branch: hover the session, click ··· (Session options), choose Switch to worktree…, then + New worktree…. ("Worktree" is git's word for a branch copy in its own folder.) Granular first summarizes the conversation so far (see Long conversations), then the session continues in the new copy. The agent must not be mid-task: if it is, you'll see "Finish or stop the current turn before switching worktree."
• Give a boss a worker on its own branch: on a boss session, open Session options, choose Create a worker session, then In a new worktree.
• Give one terminal tab its own copy: in the Terminal tool, click the + button (New terminal) next to the tabs, then New in its own copy. The tab shows Setting up its own copy… while Granular makes a branch copy in the same Granular Worktrees folder, and a branch icon marks the tab. If you close the chat while that copy holds work that isn't merged yet, Granular names it in the close warning and keeps the copy on disk.

What you'll see

• A new session appears in the sidebar, named after the branch, with a small branch icon on its row.
• The session's terminal, files and preview all point at the branch copy, not the main folder.
• The copy starts from the last commit of the main copy. Changes in the main folder that haven't been committed yet are not in it.

Where its files live

Branch copies live in a folder called Granular Worktrees in your home folder (the folder with your user name), sorted by project:

Granular Worktrees / <your project's folder name> / <branch name>

A slash in the branch name becomes a dash in the folder name, so design/homepage is stored as design-homepage.

To open the folder, expand the Main section at the bottom of the sessions sidebar, click the worktrees count, hover a branch, and click the folder icon (Reveal this worktree folder in Finder, or File Explorer on Windows).

Keep track of a branch

Click the branch icon on a branch session's row to open Branch details. It shows:

• The branch name.
• Two counts: ↑ is how many commits this branch has that main doesn't (what a merge would bring in). ↓ is how many commits main has that this branch doesn't.
• clean, or how many changes are uncommitted.
• A short tip when there's something to do, such as "Clean and ahead of main. Ready to merge in."
• The buttons that make sense right now. Commit appears when there are uncommitted changes. Next to the counts, Pull main appears when main has moved on, otherwise Merge into main appears when the branch has commits to bring in.

At the bottom of the sessions sidebar, the Main section shows the same for the main copy, and lists the project's other branch copies.

How these buttons work: each one sends a written instruction to the session's agent, which then does the git work in the terminal while you watch. The instructions have safety rules built in: the agent only saves relevant files, never forces anything, and stops to ask you when something conflicts.

Merge the work into the main copy

1. Open the branch session and click its branch icon.
2. If it shows Commit, click it first. The agent saves the changes as a checkpoint and tells you exactly what it committed.
3. If it shows Pull main, click it. The agent brings the latest main into the branch so the two aren't out of step.
4. Click Merge into main.

The agent first checks the branch is based on the current main, tells you which files the merge brings, and then merges. Afterwards the main copy has the branch's changes.

If there's a conflict

A conflict means the branch and main both changed the same part of the same file, so git can't tell which version to keep. When that happens during Merge into main, Pull main or a pull from GitHub, the agent stops and walks you through it: which files, what each side changed, and what it suggests. Tell it which version to keep, or how to combine them, in plain English.

The command palette also has Git prompts (⌘K or Ctrl+K, then Git prompts). It lists every git instruction, including two that do not stop at conflicts: Catch up with main and Push a PR. The palette warns: "One-shot prompts resolve conflicts without asking. Use them with a frontier model. Nothing here is destructive: every step is a normal commit you can undo." Use them only when you're happy for the agent to decide.

Merge everything at once

To tidy up every branch copy in one go:

1. At the bottom of the sessions sidebar, expand the Main section.
2. Click the worktrees count (for example 2 worktrees).
3. Click Commit, merge & close all.

The agent goes through each branch copy one at a time: commits loose work, merges it into main, and removes the copy and its branch only if it merged cleanly. It skips any branch with a conflict, or whose session is still working, and tells you why. At the end you get a short summary of what merged and what it skipped.

Change or undo it

Move a session between branches

Open Session options, choose Switch to worktree…, and pick a branch. The list shows each branch copy and who's in it.

• If another session is already in that copy, Granular shows Worktree in use: "Granular keeps one session per worktree." Choose Jump to that session, Switch anyway, or Cancel.
• If the session you're moving has uncommitted changes, Granular shows Uncommitted changes: "Commit first, or they stay behind in the old folder when you switch." Choose Commit first, then switch, Switch without committing (the changes stay safely in the old folder), or Cancel.

Remove a branch session

Closing a branch session doesn't delete its copy or its branch. The folder stays in Granular Worktrees and the branch stays in git. This is so no work is ever lost by closing.

To remove a branch copy:

• If its work is merged: use Commit, merge & close all (above). It removes every copy that merged cleanly.
• If you want to throw the work away: ask the agent in any session of the project, for example "Remove the new-homepage worktree and delete its branch. I don't need its changes." The agent will do it in the terminal. This deletes that work for good.

You can reopen a branch copy you still have: in the Main section, open the worktrees list and click the branch. Granular opens a new session there, or jumps to the one already in it.

GitHub and other online copies

If your project is also stored online, for example on GitHub, the Main section works with it:

• Pull from GitHub appears when GitHub has changes you don't have yet. The agent brings them in and stops if there's a conflict.
• Push to GitHub appears when you have commits GitHub doesn't. The agent sends them up and never force-pushes.
• The refresh button checks GitHub for new changes. Otherwise the counts come from your computer and only update from GitHub when you refresh.

To share a branch as a pull request (a request to merge it on GitHub, where others can review it), use Git prompts in the command palette and choose Push a PR. This is the one action that writes somewhere other people can see.

Limits

• The project folder must be a git repository with at least one commit.
• One session per branch copy. Granular warns you if you try to put a second one in.
• On the Free plan, each branch session counts toward the project's 4 open sessions.
• On Windows, Git for Windows must be installed.
• There's no button to delete a single branch copy. Use Commit, merge & close all for merged ones, or ask the agent.

If the project isn't a git repository

Creating a branch session shows: "This project's folder isn't a git repository, so it has no branches to work on." The Main section and branch icons don't appear either.

To turn the folder into one, ask the agent in a normal session: "Set up git in this folder and make a first commit of everything here." Then try New session on a branch… again.

Troubleshooting

If you see "This project's folder isn't a git repository, so it has no branches to work on.", see the section just above.

If you see "Git isn't installed, so branch workspaces can't run.", install git and reopen Granular. On a Mac, git comes with Apple's command line developer tools; ask the agent in any session to help you install them. On Windows the message says to install Git for Windows from git-scm.com.

If you see "Branch names can use letters, numbers, dots, dashes and slashes.", your name has a space or another character. Try something like new-homepage.

If you see "Could not create the branch workspace" followed by more text, git refused. The most common cause is a repository with no commits yet. Ask the agent to make a first commit, then try again. If it still fails, paste the message into a session and ask the agent what it means.

If you see "This project has no home folder to branch from.", open Project settings, set a Home folder, and try again.

If you see "Worktree in use", another session is already in that branch copy. Choose Jump to to go to it.

If the branch session doesn't have work you just did in the main folder, those changes weren't committed when the copy was made. In the main copy, click Commit, then in the branch session click Pull main.

If Merge into main doesn't appear, either main has moved on (click Pull main first), or the branch has no commits to bring in yet. Changes only count once they're committed, so if you see Commit, click it first.

If the counts look out of date, click the refresh button in the Main section.

Related