Pond docs

Appearance

Architecture overview ​

Pond runs coding agents on your Mac. Each agent is Claude Code in a terminal that Pond owns, working in its own git worktree. This section explains what runs, how the parts talk, and where the limits are.

How Pond's parts talkOn the Mac: Pond.app talks to the pond-ptyd terminal helper over pond-pty.sock. Claude Code runs inside pond-ptyd's terminals in its own git worktree. Claude Code runs the pond CLI for hooks and MCP tools; the CLI talks to pond-ptyd, to Pond.app over browser.sock and feed.sock, and to the optional Pond Computer.app over computer.sock. Off the Mac, and only when turned on: the friends relay, the signed update file on pond.codes, and EU crash and usage reports.Your MacPond.appblobs, stage, sidebar,browser tile, settingspond-ptydowns every terminal,survives app restartspond CLIhooks and MCP proxies,run by Claude CodeClaude Codein a pond terminal,in its own worktreePond Computer.appoptional, holds screenand input permissionsgit worktreesread with git andfile eventspond-pty.sockptyrunshook eventsbrowser.sockfeed.sockcomputer.sockeditsOff the Mac, only if onFriends relaysealed items onlypond.codessigned update fileEU reportscrashes, usage countsYour git remotepush after your click

The parts ​

PartWhat it isWhere it runs
Pond.appThe app you see: blobs, the stage, the sidebar, the browser tile, settings.Your Mac, as a Dock app.
pond-ptydA small helper that owns every terminal. It keeps running when Pond quits or updates.Your Mac, started on demand.
pond CLIThe pond command. You use it in a shell. Claude Code runs it for hooks and MCP tools.Your Mac.
Pond Computer.appAn optional helper for computer use. It alone holds Accessibility and Screen Recording.Your Mac, only while an agent drives.
WorktreeKitThe library that reads worktrees, tests, readiness, merges and pushes.Inside Pond.app and the CLI.
Friends relayA small server that stores and forwards sealed items between friends.Off your Mac. Used only if you turn Friends on.

How they talk ​

  • Local sockets. Every process on your Mac talks over Unix sockets in the Pond folder. Each socket is mode 0600, and each server checks who is on the other end before it reads a byte. See Processes and IPC.
  • Pushed state, no polling. The helper pushes terminal events. Claude Code hooks push session events. Git folders are watched with file events. When nothing changes, Pond does no work.
  • Files. Small JSON files in the Pond folder hold projects, sessions and settings. The safety switches among them are sealed, so an agent cannot flip them by editing a file. See Storage.

What leaves your Mac ​

Your code and terminal text stay on your Mac. A few things can leave it, each one optional or off by default:

Claude Code also talks to its own provider. Pond does not handle that traffic.

Pages in this section ​

Pond is not released yet. These docs describe the current build.