Boss and worker agents

To run several agents at once, make one session the boss with Make this the boss in its … menu, then ask it in your own words to bring in workers. Each worker is its own session with its own copy of your project; the boss gives each one a task, reads their reports and merges their finished work back into your main copy.

A session is one chat plus its terminal. A boss is a session that can create and direct other sessions. A worker is a session a boss created to do one part of the job.

Use a boss and workers when a job splits into parts that don't depend on each other: building three separate pages, researching five competitors, writing tests while another agent fixes a bug.

Use a single session when the steps have to happen in order, when the job is small, or when you want to follow one line of thinking. One session is simpler and uses less of your AI account.

Before you start

• A project folder. Workers get their own copy of the project through git, a tool that tracks versions of your files. If the folder isn't a git project yet, Granular sets that up the first time a worker needs it: it turns on git for the folder and saves a starting snapshot of your files. You don't have to do anything.
• An AI account connected. Workers use the boss's account unless you ask for a different one. See Connect an AI model.
• Any plan. Bosses and workers work on the Free plan and on Pro. Free has limits on how many; see Limits.

Make a session the boss

You can use any of these. They all do the same thing.

1. In the session list on the left, hover over the session and click its … button.
2. Click Make this the boss.

Or open the command palette and choose Make this session the boss. Or, if the agent or Granular suggests it with a card in the chat, click Make this session the boss on that card (click Not now to skip).

Choose how the boss handles reports

The first time a session becomes the boss, a window titled This session is now the boss asks: "How should it handle worker reports?"

• Autopilot on (marked recommended): when the boss is idle, it acts on each worker's report by itself. It merges finished work, sends the next task and stops only for real decisions.
• Ask first: reports wait in the boss's queue until you run one. Nothing happens without your click.

Pick one and click Confirm. Click Cancel (or press Esc) and the session goes back to being a normal session. Tick Don't show this again when a session becomes the boss to skip this window next time.

What you'll see

• A crown appears next to the session's name in the session list.
• A bar above the chat shows the crown, the word Boss and an Autopilot switch. Click the switch to change between Autopilot and Ask first at any time.
• A message confirms: "Session name is now the boss. Ask it to spawn workers and delegate."

Get the boss to create workers

Ask in the boss's chat, in your own words. For example: "Split this into three workers: one builds the pricing page, one builds the FAQ page, one writes the copy."

The boss creates each worker and gives it a task written so it makes sense on its own, because a worker can't see the boss's conversation. You'll see:

• New sessions appear in the session list, tucked under the boss with a line down the left. Granular doesn't switch you to them; you stay where you are.
• Each worker starts its task straight away and works at the same time as the others.

The boss reuses an idle worker for a new task rather than making a new one. If you give a busy worker another task, it waits in that worker's own queue and starts when the current task ends. A worker holds up to 10 waiting tasks.

You can also create a worker yourself: open the boss's … menu, choose Create a worker session, then In a new worktree (its own branch and folder) or In the current branch (shares the boss's folder).

Each worker's own copy

By default every worker works in its own separate copy of the project (a "git worktree": a second folder with its own branch, sharing the same history), so workers can't overwrite each other or your main copy.

If you ask for it, the boss can instead create a shared worker that works directly in your main folder. Its edits land live, with nothing to merge later. The boss is told to use this only when you ask for it, or when the task only reads files or is trivial. A worker also ends up shared if the folder can't be made into a git project at all (for example, a folder you can't write to).

Pick a worker's engine, account, model and effort

Workers start on the same engine and account as the boss. To change that, say so when you ask:

• Engine: Claude, Codex or Gemini. "Run this worker on Codex."
• Account: which of your connected logins pays for it, named by email or label. "Use my hello@example.com account." If you set a default account for the project, the boss prefers it.
• Model: by the name the model picker shows. "Use Haiku for the grunt work."
• Effort: how hard the model thinks: Low, Medium, High (the default), X-High or Ultra.

The worker's pane shows the chosen account and model, and you can still change them with its own pickers. You can also ask the boss to use a different model or effort for one task only.

When you switch the boss to another account

If you switch the boss session to a different AI account, a strip appears above its chat: "Also move workers to this account?" with Move N worker(s) and Dismiss.

• Move switches the boss's own workers that are still on the old account (and the same engine) to the new one.
• If some workers are busy or not open, Granular says "Some workers are busy or not open. Retry when they are ready."
• Dismiss leaves the workers where they are.

Workers and your connected apps

Workers can use the same connected apps (connectors) as a normal chat in the project, such as Gmail or Notion. See Connectors.

File permissions follow the boss

In a Claude chat, the control under the message box sets how much the agent checks with you before changing files: Auto-allow, Ask first or Plan (read-only). A new worker starts with the same setting as its boss, so a worker never sits waiting for approvals the boss didn't expect. You can change it in the worker's own pane.

(This is separate from the boss's Autopilot on and Ask first choice above, which is about worker reports, not file changes.)

How the boss's work reaches you

When a worker finishes a task the boss gave it, a report lands in the boss's queue (the list of waiting messages above the boss's chat box), labelled Worker · name. It says whether the task finished, paused, failed or went idle, which files changed and what the worker said last.

• With Autopilot on, an idle boss runs each report by itself, one at a time. These runs are marked Autopilot · so you can tell them apart from the ones you started. As a safety cap, the boss starts at most 20 of these runs in an hour. After that, reports wait and the boss bar shows a ⚡ N reports waiting · run button.
• With Ask first, reports arrive paused. The boss bar shows N reports waiting · run. Click it to run them. You can also run, reorder or remove any queued report like any other queued message.

Clicking reports waiting · run also resets the hourly cap.

The boss is told to stop and tell you, instead of acting, when a worker errored, got stuck, hit a merge conflict, or wants to do something destructive, out of scope or that costs money.

Talk to a worker or watch its preview

A worker is a normal session with its own chat and terminal. Click it in the session list to open it. You can read what it's doing, type to it directly, and open its preview. Because it works in its own copy, its preview shows that copy, not your main one.

Messages you type straight into a worker don't send a report to the boss. Only tasks the boss sent do.

Merge a worker's work

When a worker's task is done, the boss merges it: it saves everything the worker changed and folds that into your project's main copy. The boss usually does this itself (with Autopilot on), or when you ask: "Merge the pricing worker."

After a merge, open the preview to see the combined result.

If two changes clash (a "merge conflict": the worker and your main copy changed the same lines differently), Granular does not merge. Your main copy is left untouched. The boss tells you which files clash and asks you to decide: keep the worker's version, keep the main copy's version, or have a worker combine them.

A shared worker has nothing to merge, because its changes are already in your main folder.

Change or undo it

Dismiss a worker

Ask the boss: "Dismiss the FAQ worker." The boss stops anything the worker is running, closes its pane, and moves the worker's separate copy to the Trash (the Recycle Bin on Windows). Nothing is deleted for good, so you can still restore it from there. A message confirms it.

Granular only ever moves a worker's own copy, and only when the worker is idle and has no task waiting. It never touches your main folder or another worker's copy.

Unmerged work is protected. If the worker still has changes that were never merged, the boss refuses and says how many unmerged changes and unsaved files it has. Either ask it to merge first, or tell it plainly that you want that work thrown away. It only discards work when you say so.

Stop a session being the boss

Open the boss's … menu and click Demote from boss, or choose Demote boss to a normal session in the command palette. You'll see "Session name is a normal session again." If you have more than one boss, use the … menu, so you choose which one steps down.

Its workers are parked: they keep their panes and their work, but no boss directs them and their reports go nowhere. To give a parked worker to a boss, drag it onto that boss in the session list. A boss can only direct workers it owns; it can't take over parked workers or another boss's workers by itself.

Move or detach a worker

• Hand a worker to another boss: drag it onto that boss in the session list.
• Make a worker an ordinary session: open its … menu and click Detach from boss, or drag it out to the top level of the list.

You can have more than one boss in a project. Each directs only its own workers.

When a worker stops partway

It hit the step limit

Every run, the boss's and each worker's, has a step limit per request, a safety cap Granular sets (not your AI plan's limit). A worker that reaches it pauses and keeps its progress. Its report says "paused at the step limit", and the boss resumes it with "continue where you left off." With Autopilot on, that happens by itself.

In any session, including the boss, a message in the chat says the run reached Granular's step limit, with a Continue button. Click Continue to pick up where it left off.

To avoid this, ask the boss for smaller tasks. It's told to split big features into a sequence of small tasks and to tell each worker to save its work early.

It's waiting for an answer in its terminal

Sometimes a command a worker runs stops and asks a question, like "Ok to proceed? (y)". The worker's pane shows The command is waiting for your answer with the question, a box to type in, and Send and Cancel.

The question also reaches the boss. If it's harmless and the answer is obvious from the task, the boss can type it in for the worker. It will never answer a request for a password or secret, or a confirmation that deletes or changes something that can't be undone. Those always stay with you: open the worker and answer in its pane.

Limits

• On Free, a boss asked for a third worker is refused. Reuse an existing worker, dismiss one, or upgrade.
• Workers are sessions, so on Free a project with a boss and two workers has room for one more session.
• Each worker uses your AI account like any session. Several workers on one account share that account's limits and can slow each other down.

See Plans and pricing.

Troubleshooting

If you see "Your plan includes 2 workers per boss session. Upgrade to Pro for unlimited workers."
The boss already has two workers on the Free plan. Ask it to reuse one of them for the new task, or dismiss one it no longer needs. To run more at once, upgrade to Pro.

If you see "This project hit your plan session limit" (and the upgrade window opens)
The project already has 4 sessions on Free, and a new worker would be a fifth. Close a session you're done with, ask the boss to reuse an existing worker, or upgrade to Pro.

If you see "Could not create the worker's isolated branch workspace"
Granular couldn't make the worker's separate copy, so it didn't start the worker rather than let it edit your main folder. Ask the boss to try again. If it keeps happening, the message includes the reason git gave; share it in a new session and ask the agent to fix it.

If you see "… workspace is missing. Recreate its copy before sending another task"
That worker's separate copy is gone (for example, it was moved or deleted outside Granular). Granular won't let the worker fall back to your main folder. Ask the boss to dismiss that worker and create a new one.

If a worker failed and the report includes a short error
The boss's report now carries a short summary of what went wrong. Read it, then ask the boss to retry or try another approach.

If you see "The worker pane did not come up in time. Try again."
The worker's pane took too long to open. Ask the boss to try again.

If you see "... is an orphaned worker - the boss that spawned it stepped down, so it is parked."
That worker's boss was demoted or closed. Drag the worker onto the boss you want in the session list, then ask again.

If you see "... belongs to another boss session."
A boss can only direct the workers it created. Ask that worker's own boss, or drag the worker onto this boss.

If you see "... work conflicts with the main copy on: ..."
Nothing was merged and your main copy is unchanged. Tell the boss which version to keep, or ask it to have a worker combine the two.

If you see "This worker still has ... that would be lost."
The boss tried to dismiss a worker with unmerged work. Ask it to merge first. If you really don't want that work, say so plainly and it will discard it.

If you see "No account matches ..." or "... is ambiguous - it matches: ..."
The boss couldn't tell which connected account you meant. The message lists your accounts; repeat the request using one exactly as listed, for example the full email.

If you see "... account cannot serve model ..."
That account has already failed with that model. Pick a different model for this account, or a different account for this model.

If you see "Only a boss session can use worker tools."
The session isn't the boss (or stopped being one). Make it the boss again from its … menu, then repeat the request.

Related