Skip to content

Worktrees and shipping a PR

Each task works in a worktree: its own branch in its own folder, made from your repo. Ten agents can work at once and never collide, and your own checkout stays as you left it. When the work is good, wisp commits it, pushes it and opens the pull request.

Worktree or in place

New tasks get a worktree by default. To work in the project folder itself:

In New task (N), click This computer · Worktree in the footer and switch it to work in place. The choice is kept for your next tasks. Settings → General → Worktree per task sets the default.

In the browser (wisp --browser, or your cloud wisp) it’s the same window, menus and keys.

A project can say how its worktrees work: commands to run in a new one, files to copy in, and what to do when a task is done.

projects:
api:
path: https://github.com/acme/api # or the folder's absolute path
setup: ["npm ci"]
worktree:
include: [".env"] # untracked files copied into each worktree
onDone: remove-clean # ask | remove-clean | keep
cleanupDays: 7
fixConflicts: true # an agent resolves PR conflicts by itself

The first time a repo asks to run its own setup, wisp holds the turn and asks you (see A held turn).

Read the changes

Open the side panel (]) on its Changes tab, or press D: every file the task changed, with + and − counts against the base branch. Comments you leave on lines go to the agent when you send them.

The side panel open beside a task on its Changes tab, with the PR, Shell and Preview tabs next to itThe side panel open beside a task on its Changes tab, with the PR, Shell and Preview tabs next to it

Ship it

Shipping commits what’s uncommitted, pushes the branch and opens a pull request (or pushes to the one it has).

Press Ship at the top of the task (S). Check the title and description (Write it with … has the agent write them), tick Open as a draft if you want, then Commit & open PR.

Checks, reviews and conflicts

The PR tab follows the pull request: its checks, its reviews and comments, and whether it can merge. wisp checks GitHub every minute.

  • A failing check: Ask to fix puts the check’s name and the end of its log in the reply box. Read it, then send.
  • A review comment: it lands in the reply box the same way, to send to the agent.
  • Conflicts with the base branch: Fix conflicts sends the task a follow-up to merge its base in and push. With Settings → General → Auto-fix PR conflicts on, it does that by itself.

Side panel → PR (or press P). The same buttons show on the PR strip at the top of the task.

Merge

Merging squash-merges the PR on GitHub, fast-forwards your local base branch, and removes the worktree unless it holds uncommitted work.

PR tab → Merge, then Merge PR. If checks fail or no other harness reviewed it, wisp says so first; Merge anyway goes ahead.

Tidy up

Finished worktrees are cleaned up after a while. A worktree that holds work is never removed without your yes.

Settings → Computers → Worktrees lists them, with how much room they take. On a task, ⋯ at its top right → Task options › Keep worktree keeps it out of the cleanup.

Before you merge, you can have another harness read the diff: see Review by another agent.