Worktrees

Each task usually runs in its own git worktree, so several agents can work on one repo without stepping on each other. Pond shows every worktree as a row in the sidebar.

The worktree row

A worktree row has two lines. The first has the branch name, a primary chip for the main worktree, and a green Ready chip when the branch can be merged (see Review and merge). On the right it shows how far the branch is ahead of and behind the default branch, such as "↑3 ↓1". When something needs a look, one short phrase joins it: red "2 checks failing", or "PR #12" once a draft pull request exists. Click "PR #12" to open it.

The second line has the changes ("4 files" or "clean"), the test state ("✓ 487" or "✕ 2 failing"), and the word "overlap" when another worktree changes the same file.

Ahead and behind compare with your local default branch. Pond never fetches by itself.

Under each worktree row are its agents, then its shells.

The worktree card

Click a worktree row to select it. New tasks then go there. Click it again to open its card under the row. A worktree whose folder is gone shows one line and Prune. One whose commits are already on the default branch shows "merged" and Remove worktree…. Otherwise the card shows:

• Up to six changed files, each with lines added and removed. Click a file to see its git diff.
• The last test run: the command, how many passed and failed, when, and on which commit. If the code changed since, the card says the result is older than your changes.
• The overlap, when another worktree of the same repo changes the same file.
• Three merge checks: committed, tests pass on this commit, and no conflicts with the default branch. When there is a conflict, the card lists up to five of the files and offers Ask the agent to fix (see Review and merge).
• The pull request and its checks, when the branch has a draft PR (see Review and merge).
• A line with the preview address, when the worktree's dev server is known. Click it to open the browser preview.
• The Merge… button, and next to it Run tests, or Push and open draft PR… when the worktree is Ready and push is allowed for the project.

The row menu

A worktree row's menu has New task in this worktree, New shell, Run, Reveal in Finder, Copy branch name, Open in your editor, Pin, Merge…, Push and open draft PR… (only when push is on for the project), and Remove worktree…. A worktree whose folder is gone also has Prune. An agent row's menu has Open, Show card, Copy branch name, Open in your editor, Pin, Later… (when the agent waits on you) and End agent….

Later

When an agent needs you, has finished, or has crashed, and you want to deal with it after something else, choose Later… in its row menu, or select the row and press L. Pick For an hour, Until tomorrow 9:00 (before 9 in the morning it says Until 9:00 and means that morning) or Until it changes. The row moves to a quiet Later list under Projects that shows when it comes back. While it is there it does not count in the Dock number or the bell, and Pond sends no notification for it.

It comes back by itself when its time is up, or as soon as the agent does something new: you type to it, it asks another question, or it finishes. Wake now in the row's menu, or L again, brings it back at once. Later stays across a restart of Pond. The agent's blob keeps its own face the whole time.

Open in your editor

Open in Cursor (or VS Code, Zed, Xcode, Sublime Text) opens the worktree's folder in that editor. The item names the editor Pond uses and is missing when none of the five is installed. Pond uses the one you chose in Settings › General › Open worktrees in, or else the first it finds, and looks only in /Applications and ~/Applications. For Xcode it opens the workspace, project or Swift package in the folder. The command Cmd-K offers does the same for the selected worktree, and pond open does it from a terminal.

Pinned

Pin on a worktree or agent puts it in a Pinned list above Projects, with its own dot. Unpin takes it out. A pin whose worktree or agent is gone is not shown.

Run a dev server

Run starts the project's run command in its own terminal in that worktree. Set the command with Set run command… on the project row, or with pond project add . --run "…".

Pond sets PORT to a free port on 127.0.0.1 that stays with the worktree until you remove it. Several worktrees can run their dev servers at once. Next and Express read PORT. Vite does not, so write npm run dev -- --port $PORT --strictPort. When the server prints its address, the browser preview can show it.

Remove a worktree

Use Remove worktree… in the row menu, or pond worktree remove <name>. If the worktree was started from your own branch, the branch stays. Pond refuses when the worktree has uncommitted changes, commits that are not merged into the default branch, a lock, or an agent still open in it. See the CLI reference for --force.

The project row

A project row's menu has New task here, Reveal in Finder, Set test command…, Set run command…, Sync with GitHub…, Push and draft PRs…, Past sessions… and Remove from Pond. The setup command and the files copied into new worktrees have no menu item yet: set them with pond project add (see the CLI reference). Removing a project from Pond leaves its files alone.