Coding agents
pond is a command line tool and MCP server that comes with Mergepond. Claude Code, Codex and other coding agents use it to start a task in a worktree of its own, set up by the repository's recipe, and to say where the work stands. The worktree shows on the Worktrees tab, marked working, ready for review or done. pond is free, and Mergepond doesn't need to be running for it to work.
Where to find it
- Mergepond › Install Command Line Tool… puts
pondon your PATH. - Worktrees tab › gear: the Coding agents and Agent branch names settings, and Share with the team.
- Worktrees tab (⌘3): the worktrees agents make, with what each agent said about them.
pond helpin a terminal lists every command.
What pond is
Mergepond bundles pond at /Applications/Mergepond.app/Contents/Resources/agents/pond. It reads the same repository and the same project settings files as the app, and it writes what an agent says about a worktree into a small file, mergepond.json, in that worktree's own Git directory (.git/worktrees/<id>/). That file never shows in git status and goes when the worktree is removed, and the app reads it whenever it lists worktrees. So an agent can make and mark worktrees with the app closed, and the board is right the next time you open it.
pond does four things: make a worktree (and run the setup recipe), list worktrees and their status, mark a worktree with a state and a note, and save your choice about whether agents should use worktrees in a repository. Run as pond mcp, it offers the same things as MCP tools on stdin and stdout.
The plugin for Claude Code and the Codex files live in Webb-Ventures/mergepond-plugins, under the MIT licence. pond itself and Mergepond are proprietary; pond comes free with Mergepond and works on Free.
Put pond on your PATH
| Where | How |
|---|---|
| Your Mac | Mergepond › Install Command Line Tool… links /usr/local/bin/pond to the copy inside the app. If /usr/local/bin isn't writable, macOS asks for an administrator's password: "Mergepond wants to add the pond command to /usr/local/bin." A toast then reads "Installed pond at /usr/local/bin/pond. Run pond help, or see mergepond.dev/docs/coding-agents to connect a coding agent." If something else is already at that path, Mergepond says so and leaves it alone. |
| Homebrew | brew install --cask webb-ventures/tap/mergepond links pond from the app bundle, from 1.0.6. |
| An SSH host | The first time Mergepond opens a repository on a host (Pro), it uploads pond-<version> beside the remote helper in ~/.mergepond/agent/, links ~/.mergepond/bin/pond to it, and links ~/.local/bin/pond to that when ~/.local/bin exists and the name isn't taken by something else. If ~/.local/bin isn't on the host's PATH, add ~/.mergepond/bin. |
The Claude Code plugin finds pond on your PATH, or falls back to the copy in /Applications/Mergepond.app, so it works without this step. Codex's configuration runs pond by name, so for Codex, and for agents on SSH hosts, pond has to be on PATH.
Claude Code
- In Claude Code, run
/plugin marketplace add Webb-Ventures/mergepond-plugins. - Run
/plugin install mergepond@mergepond.
The plugin adds three things:
| Part | What it does |
|---|---|
The mergepond MCP server | Runs pond mcp, from your PATH or from inside /Applications/Mergepond.app. The five tools below. |
The worktrees skill | Tells Claude when to use a worktree: ask you once how to work in a repository, start tasks in a worktree with create_worktree, work only in the folder it returns, commit as it goes, and mark the worktree for review with a note when something is ready. |
| Two hooks | UserPromptSubmit runs pond hook claude and marks the session's worktrees working. Stop runs the same and marks the ones still working as ready for review. See Hooks. |
Codex
- Register the MCP server:
codex mcp add mergepond -- pond mcp. - Add the text of
codex/AGENTS.mdto yourAGENTS.md, in the repository or in~/.codex/AGENTS.md. It tells Codex to callworktree_policyat the start of a session, start tasks withcreate_worktree, mark worktrees working and review, and never remove one. - In
~/.codex/config.toml, give the server a longer tool timeout, so a big install finishes within onecreate_worktreecall:
[mcp_servers.mergepond]
command = "pond"
args = ["mcp"]
tool_timeout_sec = 600Codex has no hooks, but it runs one notify program at the end of each turn. To have it mark the turn's worktrees ready for review, add this at the top level of config.toml, before any table, unless you already use notify for something else:
notify = ["pond", "hook", "codex"]Other agents
Any MCP client that can start a stdio server can use pond mcp. The server is called mergepond, and a typical entry looks like this:
{
"mcpServers": {
"mergepond": { "command": "pond", "args": ["mcp"] }
}
}The server names the agent from the client's own name during the handshake: Claude Code, Codex, Cursor and Gemini CLI are recognised, and any other client is shown under the name it gives. That name is what the board shows and what fills <agent> in branch names.
An agent that only has a shell can run pond directly. Every command takes --json for output it can parse, and --agent <name> to say who is working; without --agent, pond recognises Claude Code and Codex from their environment variables.
The isolation choice
Whether an agent works in a worktree is your decision, per repository. The choice is called isolation and has three values:
| Value | In Worktree settings | What the agent does |
|---|---|---|
always | Always in a worktree | Before changing code for a task, makes a new worktree and works there. |
when-asked | Only when I ask | Works in the folder it was started in, and makes a worktree only when you ask for one, for a separate branch, or for work in parallel. |
ask | Ask before each task | Asks you, before each task that changes code, whether to use a new worktree. |
| not set | Ask me the first time | Asks you once, before changing any code, which of the three you want, then saves your answer. |
The answer is saved to .mergepond.local.toml at the root of the repository's main worktree, under [agents] as isolation, which only you have. Three ways to set or change it:
- Let the agent ask. With the Claude Code plugin, a hook reminds Claude on the first prompt of each session while the repository has no choice yet; the MCP server's
worktree_policytool says the same to any client. - Worktrees tab › gear, the Coding agents menu. Tick Share with the team to save it to
.mergepond.tomlinstead, so everyone who clones the repository gets the same answer. pond policy always,pond policy when-askedorpond policy askin a terminal.pond policy clearforgets it, so the agent asks again.pond policyalone prints the current choice.
Agent branch names
When an agent starts a task with a few words about it rather than a branch name, pond names the branch from the Agent branch names pattern in Worktree settings, agent/<agent>/<task> by default. It is saved as branch under [agents] in the project settings files.
<agent>is the agent's name, lower-cased with spaces turned into dashes:claude-code,codex. If no agent is known it becomesagent.<task>is the task text treated the same way: "Fix the login redirect!" becomesfix-the-login-redirect. Letters, digits,.and_stay and are lower-cased; any run of other characters becomes one-; the result is cut at 48 characters, and a leading., a..or a.lockending go, because Git refuses them. If nothing is left, the part istask.{agent}and{task}work too. The pattern must contain<task>, so every task gets its own branch; Worktree settings refuses to save without it.- If the name is already a branch,
pondadds-2,-3and so on.
So "add dark mode" from Codex becomes agent/codex/add-dark-mode, and the worktree folder follows the folder pattern, ../<repo>.worktrees/agent-codex-add-dark-mode by default.
MCP tools
pond mcp offers five tools. Every tool takes an optional repo, a folder in the repository; it defaults to the folder the server was started in. Tools that act on one worktree take worktree: its branch, path or folder name, defaulting to the worktree that holds repo.
| Tool | What it does |
|---|---|
worktree_policy | Without isolation, returns the repository's choice and what the agent should do about it. With isolation, saves the choice to .mergepond.local.toml and returns the same. |
create_worktree | Makes a branch for the task, checks it out in a new folder, runs the setup recipe and marks the worktree working, with the agent's name and note. Returns the folder to work in. |
list_worktrees | Every worktree with its branch, folder, uncommitted changes, commits ahead and behind, whether it is merged or on the remote, and what agents said about it. |
worktree_status | One worktree, the same fields, plus the setup recipe's progress. |
mark_worktree | Sets the worktree's state and note for the board, or clears them. |
Parameters
| Tool | Parameter | Type | Meaning |
|---|---|---|---|
worktree_policy | isolation | always, when-asked or ask | The user's choice, to save. Leave it out to read. |
create_worktree | task | string | A few words about the task. Names a new branch with the agent branch pattern. |
branch | string | An exact branch to check out, or to create if it doesn't exist. Beats task. | |
pr | integer | A pull request number to check out instead of a branch, as in the New worktree sheet. | |
from | string | Where a new branch starts. Default: the current HEAD. Refused for a branch that already exists. | |
note | string | A line about the task, shown on the card. | |
setup | boolean | Run the setup recipe. Default: true. | |
worktree_status | worktree | string | Which worktree. |
wait_seconds | integer | Wait up to this long for a running setup to finish, at most 50. | |
mark_worktree | state | working, review, done or clear | Required. clear removes the state, note and agent name. |
note | string | One line, such as what is ready or what is blocking. Shown on the card with the time it was set. | |
worktree | string | Which worktree. |
What they return
create_worktree returns path, branch and setup. It answers within 50 seconds, because MCP clients give up on long calls: setup.done says whether the recipe finished, setup.ok whether every step passed, and setup.steps lists each step with its status and the last lines of its output. If done is false the recipe carries on in the background, and worktree_status with wait_seconds reports when it finishes. If a step fails, the worktree still exists and the branch is checked out; only that step and the ones after it didn't run.
list_worktrees and worktree_status describe each worktree with state, one of folder missing, merged, branch gone on the remote, has changes, commits to push or clean; changes, ahead, behind and upstream; notOnRemote, a sentence when the branch has commits the remote doesn't; lastCommit; main and here, true for the main folder and for the worktree the call was made from; agent, with the mark's state, note, agent and updated; and setup.
worktree_policy returns isolation (or null), decided, do (a sentence telling the agent how to work), branchPattern and savedIn.
The pond command
The same operations from a terminal, for you or for an agent without MCP.
| Command | What it does |
|---|---|
pond new <branch> | Checks out a branch, new or existing, in its own worktree and runs the setup recipe. Prints the folder alone on stdout, so cd "$(pond new fix/login)" works; progress goes to stderr. |
pond new --task "<words>" | The same, with a new branch named by the agent branch pattern. |
pond new --pr <number> | The same for a pull request. |
pond list | Every worktree, one per line: branch, state, what an agent said, and path. A * marks the worktree you are in. |
pond status [<worktree>] | One worktree in full, as JSON. Default: the one you are in. |
pond mark <state> [<worktree>] | working, review, done or clear, with --note "<text>". |
pond remove <worktree> | Deletes a worktree's folder; the branch stays. Refuses the main folder, and refuses a worktree with uncommitted changes or commits that aren't on the remote unless you add --force. |
pond policy [<choice>] | Prints the isolation choice, or sets it: always, when-asked, ask or clear. |
pond mcp | Serves the tools above on stdin and stdout. |
pond hook <claude|codex> | For agents' hooks. See Hooks. |
pond help, pond version | What they say. |
<worktree> is a branch, a path or a folder name. pond new also answers to add and create, list to ls, status to st and remove to rm.
Flags
| Flag | On | What it does |
|---|---|---|
--repo <dir> | Every command | The repository to work on, any folder inside any of its worktrees. Default: the current folder. |
--json | Every command | Print the result as JSON, and nothing else. |
--agent <name> | Every command | Who is working, for the board and for <agent> in branch names. Without it, pond recognises Claude Code and Codex from their environment. |
--from <ref> | pond new | Where a new branch starts. Default: the current HEAD. |
--note "<text>" | pond new, pond mark | A line for the card. |
--no-setup | pond new | Skip the setup recipe. |
--path <dir> | pond new | Put the worktree here instead of where the folder pattern says. |
--force | pond remove | Remove even with uncommitted changes or unpushed commits. The changes are lost; the branch still stays. |
Unlike the MCP tool, pond new waits for the whole recipe before it prints the folder.
Marks on the board
What an agent says about a worktree sets the card's state pill and column on the worktree board, from Mergepond 1.0.7 part of Pro.
| Mark | Pill | Column |
|---|---|---|
working | "Claude Code working" (or the agent's name) | Working |
review | "Claude Code: ready for review" | Ready for review |
done | "Claude Code: done" | Ready for review |
The note, if there is one, shows under the pill with how long ago it was set; otherwise the card shows the last commit as usual. A worktree whose setup recipe is still running shows "Setting up" with the steps, and one whose recipe failed shows "Setup failed", both in Working. Marks give way to what Git says once the branch is merged, gone from the remote or its folder is missing: those cards go to Merged or gone as usual, where you remove them.
On Free, the Worktrees tab lists every worktree without its state or mark; pond list in a terminal shows them on either.
Hooks
Hooks keep the board honest without the agent having to call mark_worktree for every turn.
Claude Code. The plugin's UserPromptSubmit hook marks the session's worktrees working when you send a message, and clears a stale "ready for review" note. Its Stop hook marks the ones still working as ready for review when Claude stops. A session's worktrees are the ones Claude made through the MCP server or pond new in this session, plus the worktree Claude is running in, if it is one (never the main folder). On the first prompt of a session in a repository with no isolation choice, the hook also adds a reminder to the prompt, telling Claude to ask you once and save the answer. Each hook has ten seconds and never fails the prompt: if pond is missing or anything goes wrong, Claude carries on.
Codex. notify = ["pond", "hook", "codex"] runs pond hook codex at the end of each turn, which marks the turn's worktrees ready for review. There is no event when a turn starts, so Codex's worktrees are marked working when they are made, and again when Codex calls mark_worktree.
What agents can't do
- Remove a worktree. Neither the MCP server nor the skill offers it. You remove worktrees on the Worktrees tab, from the sidebar, or with
pond remove. - Delete a branch.
pond removealways keeps the branch and its commits. - Work in your checkout.
create_worktreeandpond newalways make a new folder; the skill tells the agent to work only there. - Change
.gitignore..mergepond.local.tomlis kept out of Git through.git/info/exclude. - Commit, push or merge through
pond. Those are Git, in the agent's hands and yours, as before.
Free and Pro
pond, the plugin and the Codex setup are free and work on Mergepond Free. The board that shows the marks is part of Pro from 1.0.7; see Worktree board: Free and Pro. Repositories on SSH hosts, and pond on those hosts, need Pro.