The remote helper
When you open a repository on an SSH host, Mergepond copies a small program called pond-agent to that host and talks to it over the SSH session. It runs Git and reads files there, as you. It opens no ports, installs nothing system-wide, and exits when the session ends.
Where it lives
The helper is uploaded to ~/.mergepond/agent/ in the SSH user's home, as a file named for its version: pond-agent-<version>. Each Mergepond release bundles builds for Linux and macOS on x86_64 and ARM, and uploads the one that matches the host's uname -sm. The upload goes to a temporary name and is renamed into place, so a dropped connection never leaves a half-written binary. When you upgrade Mergepond, the next connection uploads the new version beside the old one.
To remove it from a host, delete ~/.mergepond/agent/. Mergepond uploads it again on the next connection.
How it starts and stops
Mergepond opens one SSH session per host with your system ssh (your config, keys and agent apply) and runs pond-agent serve on it. The helper speaks a framed protocol on the session's stdin and stdout. When Mergepond closes the session, or the connection drops, stdin closes and the helper exits. There is no daemon to stop and no port to close.
Run on the host directly, pond-agent --version prints its version and pond-agent serve waits for frames on stdin. There is nothing else to configure.
What it does
The helper answers a fixed set of requests from the app:
| Request | What it does on the host |
|---|---|
| hello | Reports its version, protocol version, OS, architecture and whether git is installed. |
| git | Runs a git command in a repository, with GIT_TERMINAL_PROMPT=0 and LC_ALL=C, and returns the exit code and output. This carries every Git operation Mergepond performs: log, status, diff, stage, commit, fetch, push, rebase. |
| exec | Runs a command in a folder. Used for worktree setup recipes and for the du that measures worktree size. |
| fs.read, fs.write, fs.stat, fs.countlines, fs.mkdirp, fs.canonicalize, fs.readdir, fs.remove | File operations Mergepond needs around Git: reading a file to show it, writing a resolved conflict, checking a path, listing a folder. |
| watch, unwatch | Starts or stops watching a repository for changes. |
Git never prompts through the helper. If a push or fetch needs credentials that the host's Git can't supply without a prompt, the operation fails with Git's message rather than hanging.
How it notices changes
There is no file-system watcher on the host. A watched repository is polled every two seconds: the helper hashes the metadata of HEAD, the index and the refs, and the output of git status --porcelain. When the hash changes it tells Mergepond, and the window refreshes. This is why a change made in a shell on the host shows up in Mergepond within a couple of seconds rather than instantly.
Version matching
The protocol has a version. If a running helper speaks a different one, Mergepond reports "pond-agent X on host speaks protocol N, Mergepond Y needs M." and uploads the version it needs on reconnect.
What it never does
- It never opens a network port or accepts connections. Everything travels over your SSH session.
- It runs as the SSH user you connected as, with that user's permissions, and installs nothing outside
~/.mergepond/agent/. - It never copies repository contents to your Mac. Diffs and file contents are read on demand and shown; nothing is cloned.
- It never stores credentials. Git on the host uses whatever that machine's Git is already configured with.
Free and Pro
The helper is only used for repositories on SSH hosts, which need Mergepond Pro. See Remote repos over SSH.