Bloom Docs

Workspaces and agents

How Bloom isolates work, runs agents and keeps review and delivery attached to the same workspace.

Workspaces

A workspace is a real git worktree on your disk, on a branch of its own, under ~/bloom/workspaces. That is the whole idea: two agents working at once are two directories and two branches, so neither can see the other's half-finished edits, and neither can overwrite them.

When Bloom creates one it copies your .env files into it and runs your project's setup script there, so you do not have to. Build caches still start cold, the same as any new checkout.

Archiving a workspace removes the worktree and, if you ask it to, the branch. Because that is a directory being deleted, Bloom works out what it would destroy before it does it: uncommitted changes, files git has never been told about, ignored files that differ from your main checkout (the copied .env is the usual one), commits an agent left behind on a detached HEAD, a turn still running, and, when the branch goes too, commits that exist on no other branch, tag or remote. If nothing is at stake it archives without asking. If something is, it stops and names every item, one line each, and you decide.

A pull request GitHub says it merged takes the commits off that list. Git's own answer is not enough there, because a squash merge rewrites a branch's commits onto the base and leaves git reporting the branch as unmerged when every line of it has already landed.

Archived workspaces stay in the sidebar's archive. Restoring one cuts the worktree again from the branch: from this Mac if the branch is still here, from the remote if it is not. If it is gone from both, the transcript is still there to read, but there is nothing left to check out.

Working with an agent

The middle column is the transcript: one row per thing the agent did, with the reasoning between them. Rows expand. A tool call shows what it was given and what came back.

• The composer is at the foot. Type and press ↩, or ⌘↩ if you prefer it. ⇧↩ makes a new line, because a prompt is often a paragraph.
• Drag a file in, or paste a screenshot. Bloom copies it into the worktree the agent is standing in and refers to it by a path relative to that, so the agent can actually open it. Dictation works in the box as well, the same as in any other Mac app.
• Model, effort and permission mode are the controls under the box, and they are per session rather than global.
• Permission questions appear in the transcript, where the thing being asked about is. Nothing pops over what you were reading. The prominent button grants the narrowest rule that stops the question coming back, and the rule is printed before you press it.
• Questions are answered, not approved. When an agent asks you to choose between options, you get the options.
• Stop is ⌘. The turn ends and the transcript says so.
• Sessions are tabs within one workspace: ⌘T starts a fresh one against the same worktree, keeping the old one intact.