Perch
Guide contents

Field guideStart work

Opening a pull request

Open a GitHub pull request from the commits on your branch. Perch keeps the worktree’s discussion and agent runs with the PR.

Fill in the pull request

Check the Pull request row in Conversation. If it shows uncommitted files and no commits past the base, commit the changes you want to publish.

Pull request status showing nine uncommitted files and no commits past main

Once you have a commit ahead of the base, click Open pull request….

  • Title starts with the commit subject for a single commit or the item’s name for several.
  • Description uses the repository’s PR template, looking in .github/, the root, then docs/. Without a template, it uses the single commit’s body or a list of commit subjects. Start Work adds Closes #<n> for the source issue or PR. You can mention people with @ or insert file paths as inline code.
  • Base starts with the branch you worked from. You can choose another GitHub branch.
  • Draft is off by default. Turn it on to open a draft PR.
  • Write with Claude or Codex drafts a title and description from a read-only inspection of the branch. Perch asks before replacing your edits. Stop cancels the request. These runs stay out of the item’s run history.

Push the branch and open the PR

Perch keeps your edits when you collapse the form or switch items, until you quit. Click Open pull request or press Cmd-Enter in the description to submit.

  1. Perch checks GitHub for an open PR from this branch. If one already exists, it opens that PR and skips the push.
  2. Perch pushes the branch without force. In your clone, Git uses your credentials and sets the upstream branch. In a clone managed by Perch, it uses Perch’s token.
  3. GitHub creates the PR. The worktree item becomes that PR in the same window, with its threads and agent runs intact.

Only commits go into a PR. Perch lists any uncommitted files it leaves out. Finish any active Work run, switch back to the worktree’s branch, and enter a title to enable the button.

If the remote has commits you don’t have, pull or rebase in a terminal. If Git needs a password or SSH passphrase, push from the terminal, then click Open pull request again. Perch skips the completed push. The agent drafts text. You authorize the push and PR by submitting the form.

Add commits to an open PR

When your PR branch is ahead of GitHub, click Push beside the unpushed commit count on the Branch row, or Push 3 commits in the merge box. Perch refreshes the PR afterwards so you can submit a review or merge. If the branches have diverged or you’re behind, update the branch first. Perch never force-pushes.