Docs
Everything Bloom does, in the order you will meet it. If you have used git worktrees before, none of this will surprise you. If you have not, the first two sections are the ones that matter.
Getting started
Bloom needs macOS 26 or later, and at least one coding agent already installed and signed in. It runs Claude Code and Codex, using the account you already have; it does not ask you for an API key and it has no account of its own.
- Install it. Download Bloom, drag it to Applications, open it. There is no sign up.
- Add a project. Press ⌘⇧O, or use the button on the Home screen, and pick a git repository you already have checked out.
- Describe a task. Press ⌘N and write what you want done, the way you would say it to a person. Bloom names the branch from it.
That is the whole setup. The first workspace takes a few seconds longer than the rest, because your setup script runs in it.
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. Bloom checks first: uncommitted changes, unpushed commits and an open pull request each turn the confirmation into a warning that says what would be lost. Archived workspaces stay in the sidebar's archive and can be restored.
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 ⌘↩. Return makes a new line, because a prompt is often a paragraph.
- 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.
Reviewing the work
The right column lists what changed, against the merge base rather than against your last commit, so it shows the whole branch rather than the last thing the agent typed. Click a file to open its diff in the middle column, side by side or unified.
- Comment on a line and it goes back to the agent as part of your next message, with the file and line attached. This is the fastest loop in the app: read, mark the three lines you do not like, send.
- Edit the file yourself in the same view. Bloom refuses a save if the file changed on disk underneath you.
- Walk the files with ⌘⌥J and ⌘⌥K.
- Quick Look works on a changed file with the space bar, exactly as it does in Finder.
Opening a pull request
Ask the agent to open the pull request and it writes the description from a prompt template you can rewrite in Settings. Bloom reads the check runs as they come back and shows them in the window. Merging takes one more confirmation, deliberately.
This needs gh installed and authenticated. Without it everything
else in Bloom works and the pull request features are simply absent.
Terminals, browsers and panes
Every workspace has a terminal in its own worktree, so npm run dev
in one workspace cannot collide with the same command in another. Terminal
sessions are handed to tmux, so they keep running after you quit Bloom and are
still there when you open it again.
- New terminal tab: ⌘⇧D.
- New browser tab: ⌘⇧T, with the Web Inspector docked inside it.
- Split a pane: ⌘\ to the right, ⌘⇧\ downwards. Close one with ⌘⌃W.
- Rearrange by dragging a tab onto another tab, or a pane onto another pane.
Each workspace is allocated ten ports, and the first is in
BLOOM_PORT, so a run script can bind something that will not
clash with the workspace next to it.
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.
Setup and run scripts
Scripts run with both BLOOM_* and CONDUCTOR_*
environment variables set, with the same meanings, so a script written for
Conductor runs unchanged.
| Variable | What it holds |
|---|---|
*_WORKSPACE_PATH | The worktree directory. |
*_ROOT_PATH | The main checkout. |
*_WORKSPACE_NAME | The branch name, with slashes replaced by dashes. |
*_WORKSPACE_ID | The workspace's own id. |
*_DEFAULT_BRANCH | The project's default branch. |
*_PORT | The first of the ten ports allocated to this workspace. |
*_IS_LOCAL | Always 1. There is no cloud mode. |
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 |
| ⌘↩ | Send what is 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 |
| ⌘⇧D | New terminal tab |
| ⌘⇧T | New browser tab |
| ⌘\ / ⌘⇧\ | Split the pane right, or down |
| ⌘⌃W | Close the pane |
| ⌘⌥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 a Shortcuts action for starting one.
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].