Review and merge

Pond helps you see whether an agent's branch is safe to merge. It shows what changed, whether the tests passed on that exact commit, and whether another worktree touches the same files. Merging always takes your click.

See what changed

Open the worktree card. It lists the changed files with lines added and removed. Click a file and its diff opens as a tile next to the agent's terminal. The list on the left has the changed files, and the right side shows one file with old and new line numbers and green and red rows. It is read-only and has no syntax colour. Cmd-R reloads it, and Cmd-W or Esc closes it. pond open <worktree> opens the worktree in your editor.

Compare against something else

The grey words in the bar ("against main") are a menu. Choose main where the branch left it (the default), main as it is now, this commit alone, or Branch or commit… and type a branch, tag or commit; HEAD~3 works. A ref that does not exist shows one red line, and the diff on screen stays. Reopening the tile keeps your choice. In the primary worktree the first two choices read "Uncommitted changes".

Big changes

With 13 or more changed files the list becomes a folder tree. Each folder shows how many changed files it holds, folders more than two deep start closed, and the folder of the selected file is always open. Each file has a circle: click it to mark the file Viewed. The bar counts how many you have marked. A mark stays until that file's content changes, so an edit by the agent clears it, and marks survive a restart. They are kept per worktree in review-viewed.json in the Pond folder.

Notes for the agent

Click a line and type a note: Return keeps it and Esc drops it. Send n notes pastes one block into the agent's input and does not press Return, so you read it first. If the agent shows a dialog, the notes stay and the bar says why. A note keeps the target it was written against. If you switch the compare menu afterwards, notes written against another target stay in a quiet list under the diff (at most five rows, then "n more notes on other targets") with "against <target>, not shown" and a way to remove each. They still count in Send n notes, and each goes out under its own target, for example [against this commit (a1b2c3d)].

Test results without running tests

Pond reads the test summary from the agent's own terminal output. It understands the summary lines of node --test, Jest, Vitest, pytest, go test, cargo test and swift test. For each run it keeps the command, the counts, the time and the commit.

To run the tests yourself, click Run tests in the card, or run pond tests run <worktree>. Set the project's test command with Set test command… on the project row, or pond project add . --test-command "npm test". Pond runs one test run at a time.

Overlap warning

When two live worktrees of the same repo change the same file, both rows show "overlap". The card and the blob's hover card name the other branch and the files, for example "Also changed in pond/fix-port: lib/agents.mjs".

Ready to merge

A branch is ready when all four hold:

1. The worktree is clean.
2. It is at least one commit ahead of the default branch.
3. Tests passed on this exact commit and tree.
4. git merge-tree reports no conflict with the default branch.

No agent may be working there. A ready worktree gets a green Ready chip.

A branch that cannot merge

When the check finds a conflict, the worktree card lists up to five of the files, then "and n more", and one button: Ask the agent to fix. It sends the worktree's agent one message to merge the default branch into the branch, resolve those files keeping both sides' intent, run the tests and commit. Pond presses Return for that message, because you clicked the button. If you have half-typed text in the agent's input, or it shows a dialog, nothing is sent and Pond says why. With no live agent there, Pond starts one. The card checks again after the agent's next commit.

Merge

Merge… opens a sheet such as "Merge pond/fix-port into main · 3 commits · 4 files · ✓ 487 tests". The option "Remove the worktree too" is on by default.

1. Pond runs git merge --no-ff in the main worktree. That worktree must be on the default branch and clean. If it is not, Merge… is disabled and says why.
2. If git still fails, Pond runs git merge --abort and shows the message.
3. Pond never pushes as part of a merge. Afterwards, the default branch's test state reads "not run since the merge".

From a terminal: pond merge <worktree> --dry-run, then without --dry-run. Add --remove-worktree to remove it afterwards.

Push and open a draft PR

Pond never pushes by itself, and an agent cannot push. You do it, one worktree at a time.

1. Turn it on for the project: project menu › Push and draft PRs…. A sheet names the remote and asks once. It stays off until you do this.
2. On a Ready worktree, click Push and open draft PR… on its card, or choose it in the worktree's menu.

A confirm sheet shows the branch, the remote and the base. The exact git and gh commands are under Details. Return and Esc both cancel, so only a click on Push goes ahead.

• Pond pushes only that branch, never with force, and never the default branch. If the branch moved on GitHub, the push is refused.
• It opens the draft pull request with your own gh login. Pond reads and stores no token.
• If gh is missing or you are signed out, the sheet says so up front: Pond will push the branch but cannot open the PR.
• The push is blocked when a pushed commit touched agent settings or files that usually hold secrets (.env, .npmrc, ssh keys, *.pem and the like), even if the file was deleted again.
• After the push the row shows "PR #12". A second push only pushes.

To see what would happen first, run pond pr <worktree> --dry-run. It prints the remote, branch, title and the exact commands, and pushes nothing.

Checks on the pull request

When a worktree has a draft PR and push is on for the project, Pond reads its checks with gh. The row says "2 checks failing" in red when any fail. The card shows the overall result, how long ago it was read, and each failing check with a Send to agent button. That pastes one line naming the check, branch, PR and link into the worktree's agent and brings its terminal forward. It never presses Return, so you read it first. With no agent in the worktree, or one waiting on a dialog, nothing is sent.

Pond asks gh when you open a card, and every five minutes while checks are still running. It asks nothing otherwise. If gh is missing, signed out or the PR has no checks, the row stays quiet.

Compare several tries

When you started a task with "× n", the compare card shows each try's files, tests and readiness side by side. Keep this one… merges the chosen try. See Tasks.