Bloom Docs
Reference
Use this chapter when you need the exact behavior of a workspace, setting, shortcut or integration.
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.
Project settings
Bloom reads TOML settings files, layering them in this order, with later files winning. It reads Conductor's files too, so a project already set up for Conductor works with no changes.
~/.conductor/settings.toml
~/.bloom/settings.toml
<project>/.conductor/settings.toml
<project>/.bloom/settings.toml
<project>/.conductor/settings.local.toml
<project>/.bloom/settings.local.tomlThe keys it understands:
| Key | What it does |
|---|---|
scripts.setup | Runs once in a new worktree, before the agent starts. |
scripts.run | Your dev server. A string, or a table of named scripts each with a command. |
scripts.archive | Runs before a worktree is removed. |
scripts.run_mode | How run scripts are started. |
files_to_copy | Globs copied from the main checkout into each new worktree. Defaults to .env*. |
git.branch_prefix | What every branch name starts with. |
git.branch_prefix_type | How that prefix is built. |
git.delete_branch_on_archive | Whether archiving also deletes the branch. |
models.default | The model a new session starts on. |
All of this is also editable in the window: ⌘⇧, opens the settings for the current project.
Keyboard shortcuts
| Shortcut | Does |
|---|---|
| ⌘N | New workspace |
| ⌘T | New session in this workspace |
| ⌘W | Close session |
| ⌘⇧O | Add a project folder |
| ⌘F | Find a workspace |
| ↩ or ⌘↩ | Send what is in the composer |
| ⇧↩ | A new line in the composer |
| ⌘. | Stop the agent |
| ⌘⌥↓ / ⌘⌥↑ | Next and previous workspace |
| ⌘⇧U | Next unread workspace |
| ⌘⇧H | Go to Home |
| ⌘⌃S | Toggle the sidebar |
| ⌘⌥I | Toggle the inspector |
| ⌘⇧T | New terminal tab |
| ⌘⇧B | New browser tab |
| ⌘⇧D | Show the changes, and go back again |
| ⌘⇧N | Show the notes |
| ⌘\ / ⌘⇧\ | Split the pane right, or down |
| ⌘⌃W | Close the pane |
| ⌘⇧[ / ⌘⇧] | Previous and next tab |
| ⌘⌥J / ⌘⌥K | Next and previous changed file |
| ⌘E | Switch between the diff and the editor |
| ⌘S | Save the file you are editing |
| ⌘⇧E | Open the worktree in your editor |
| ⌘⇧R | Reveal the worktree in Finder |
| ⌘⇧C | Copy the branch name |
| ⌘⌫ | Archive the workspace |
| ⌘⇧, | Settings for this project |
| ⌘+ / ⌘- / ⌘0 | Zoom the text in, out, back to normal |
Deep links and Services
Bloom answers a URL scheme, with the same shape as Conductor's, so scripts written for one work with the other:
open "bloom://prompt=<urlencoded prompt>&path=<urlencoded project root>"Bloom also installs a Services item, so you can select text anywhere on the system and send it straight into a workspace, and four Shortcuts actions: start a workspace, open one, list them, and read one's status.
When something is wrong
-
An agent is missing from the list. Bloom looks for the
CLI on your
PATH. If you installed it somewhere unusual, set the path in Settings › Agents. -
Pull request buttons are missing. That is
ghnot being installed or not being signed in. - A workspace will not set up. The setup log is in the transcript, expandable, with the script's real output in it.
- Anything else. Help › Send Feedback inside the app fills in your version numbers for you, and can attach screenshots. Or write to [email protected].