Pond docs

Appearance

Task lifecycle ​

A task is one Claude Code session in its own worktree. This page follows one from start to finish.

The life of a taskA task moves through eight steps: you write the task; Pond makes a worktree and a pond branch; it copies ignored files and runs your setup command; it starts Claude Code with per-session hooks; hooks and the terminal report state; Pond checks readiness; you review the diff; then you merge locally, or push and open a draft pull request after a confirm sheet. Only you can do the last step.1New tasktext checked,project known2Worktreebranch pond/slugin repo-pond/3Setupcopy ignored files,your setup command4Claude Codesession settings,task typed in5Hooks and screenworking, needs you,done6Readyclean, ahead, tested,merges cleanly7Reviewread-only diff,notes to the agent8 · your clickMerge, or pushand open a draft PRafter a confirm sheet

1. New task ​

You start a task from the sidebar or with pond task new. Pond checks the text first: 1 to 4,000 printable characters, and no line may start with -, !, / or #. Nothing is created for a refused text. The project must be one you added to Pond.

2. Worktree ​

Pond runs git worktree add -b pond/<slug> <repo>-pond/<slug> <default branch>.

  • The folder sits next to the repo, in <repo>-pond/, so the repo's own tree stays clean.
  • The slug is 2 to 5 words from the task text, at most 40 characters. Those few words are the only part of the task text that ends up in a name.
  • The worktree starts from the default branch's commit, never from your working tree. Uncommitted changes in the repo stay where they are.

pond new --here runs in an existing worktree instead and skips this step.

3. Setup ​

Two optional per-project settings run before the agent starts:

  • Copy. Ignored files from the main worktree are copied in, by default .env and .env.local when present. Only files git ignores are copied, so the agent cannot commit them by accident. Copies are APFS clones, never symlinks, and never over a file that already exists.
  • Setup command. One command line you typed, such as npm ci. It runs visibly in the agent's terminal before Claude Code starts. If it fails, the terminal says so and waits. Return starts Claude Code anyway.

Only you set these. A file in the repo cannot set them, and neither can an agent.

4. Claude Code ​

Pond writes a settings file for this one session, sessions/<agent id>.json, mode 0600. It holds the hooks and nothing else. Then it starts:

claude --settings <session file> --session-id <uuid> [--model m] [--effort e]

The process runs in a pond-ptyd terminal that knows it is an agent: its ids, worktree and branch. When the session uses the browser, computer use or the friends feed, the matching MCP servers go into a per-session config too.

Pond waits for Claude Code's input box on the terminal's output stream, at most 30 seconds. Then it types the task as a guarded write and presses Enter. If Claude Code first asks whether you trust the folder, the task text stays in memory while you answer.

The task text goes only into the terminal. It is never put in argv, a file or a log. Your ~/.claude settings are never changed: the hooks live only in the session's own file, and pond-ptyd deletes that file when the agent exits.

5. Hooks and the screen ​

Five Claude Code hooks call pond hook: SessionStart, UserPromptSubmit, Notification, Stop and SessionEnd. Each one sends the helper the session id, the folder, and a few values from fixed lists. It never forwards the prompt, a notification message, tool input or the transcript path. Unknown values become other.

The helper also watches the terminal itself. It sees output, input you have not sent yet, and Claude Code's dialogs. Together these give each agent its state: working, needs you, idle, done or ended. The blob, the sidebar and notifications follow that state.

6. Readiness ​

A worktree shows Ready to merge only when all of these hold:

  • the worktree is clean;
  • its branch is at least one commit ahead;
  • tests passed on this exact tree;
  • git merge-tree --write-tree merges cleanly into the default branch;
  • no agent is working there.

Test results are tied to the exact tree they ran on. Pond stores the tool, the counts, the time, the commit and the tree hash, never the output.

Worktree facts come from file events on the worktree and its git folder. One read costs three git calls. When nothing changes, Pond runs no git at all.

7. Review ​

The diff tile shows the worktree's whole diff against its default branch, read-only, with untracked files as new files. Git is stopped after a size limit, and very long files are cut, so a huge diff cannot stall Pond. Your git config cannot change the diff's shape.

You can click a line and write a note. Send pastes the notes into the agent's terminal as one bracketed paste. Pond never presses Return on its own.

8. Merge, or push and open a draft PR ​

Both paths start only from your click.

Merge runs git merge --no-ff --no-edit <branch> in the main worktree. That worktree must be on the default branch and clean. If git fails, Pond runs git merge --abort. A merge never pushes. You can remove the worktree in the same step.

Push and open draft PR is off per project until you turn it on once. Then:

  • a confirm sheet names the remote, the branch and the title;
  • Return does not confirm, so you click the button;
  • the push uses an explicit refspec, so a + or --force cannot be built;
  • if the remote has commits the push would drop, nothing is forced and the work stays local;
  • the draft PR is opened with your own gh sign-in.

Pond never reads or stores a token. pond pr can only preview with --dry-run, and there is no MCP tool for pushing, so an agent cannot push through Pond.

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