Worktrees and code review
Git checkout isolation, diff sources, review comments, sync, and merge operations.
A Git worktree is a separate checkout that shares repository history with the main checkout. pi-kit can associate a thread with a worktree and use that directory for its Files, Terminal, and Changes panels.
Thread placement#
Before the first message, choose a placement above the composer:
| Mode | Directory |
|---|---|
| Local | The existing project checkout. |
| Worktree | A linked checkout created for the thread. |
Placement is applied when the first message is sent. Opening an empty Worktree thread does not create a checkout.
/worktree new creates one immediately.For Local mode, changing an existing checkout's branch may be refused if there are uncommitted changes, another running thread, or a worktree already holding the branch.
Worktree options#
The placement row provides the base, branch mode/name, carried-change option, and setup script. A detached worktree has no branch until one is created.
Carried changes come from the source checkout, not from per-thread ownership. Remember stores placement defaults for the project.
Open Settings → Projects → your project to configure the worktree directory, branch naming, cleanup policy, and setup scripts. A script can run dependency installation or copy listed files. If no script is configured, pi-kit may suggest one based on the lockfile.
Review changes#
Open Changes and select a source:
- This thread: changes against the thread's tracked baselines.
- Working tree: all current checkout changes.
- Outcome: the recorded diff for a commit, merge, or pull request.
Review mode provides unified or split diffs. Add comments to line ranges, then send the batch to pi. Comments are not sent individually as they are added.
Outcome is a historical source. Staging and reverting apply to current changes, not to the outcome diff.
Sync with the base#
Choose Sync with base from the thread menu. The dialog provides the applicable merge/rebase operation. Conflicts open in review mode. Resolve them and run the project's checks before merging back.
Merge back or open a pull request#
Choose Merge back and review the target and commit message. The flow can merge into the base checkout or create a pull request when the GitHub CLI and remote configuration support it.
Pull-request creation requires
gh authentication and an accessible remote. The resulting outcome badge links to the delivered change. Worktree removal is a separate decision; pending files or another thread using the directory can prevent removal.Move a thread#
The thread menu includes these operations when applicable:
- Hand off to local: move work from the worktree to the project checkout.
- Move into a worktree: move a Local thread into a linked checkout.
- Create branch here: give a detached checkout a branch.
A hand-off can change the main checkout's branch. Moving Local work can include all uncommitted changes in that directory, not only files edited by one thread. Disabled entries explain the blocking condition.
Concurrent work#
Threads can receive information about other agents in the same repository, including recently edited files. File indicators are advisory and do not lock files.
Worktree separation is not a tool sandbox: commands and absolute paths can reach other directories. Conversation branching also does not restore file state. Use Git and the selected Changes source to inspect the checkout before continuing.
See Troubleshooting for branch, placement, and cleanup failures.