DESIGN.md — Architecture & Design Decisions

Overview

A pi extension that manages git worktrees through tool commands and an interactive /worktree command, with tight session integration.

v1 Scope

Four tools: git_worktree_create, git_worktree_list, git_worktree_switch, git_worktree_remove
One command: /worktree (interactive picker)
Session hooks: branch display update + offer new session after switch
Out of scope: auto-worktree creation, smart defaults, persistent state

Architecture

pi-worktree.ts
├── Tools
│   ├── git_worktree_create(path, branch?, create_branch?)
│   ├── git_worktree_list()
│   ├── git_worktree_switch(target)
│   └── git_worktree_remove(path)
├── Command: /worktree (interactive picker)
└── Session hooks
    ├── Update pi's git branch display on switch
    └── Offer new session creation after switch

Key Design Decisions

Stateless Tools, Ephemeral Memory

Tools are stateless; only in-memory mapping of worktree→session during a process lifetime for back-switching. Lost on restart.

Fail Fast, No Auto-Correction

Refuse dangerous operations (existing path, current branch, uncommitted changes) with clear messages and suggested fixes. Never silently auto-correct.

Session Integration Depth (v1)

Update branch display + offer new session creation. No automatic worktree creation per branch — keeps complexity down and avoids assumptions about workflow.

Tool Behaviors

Tool	Key Behavior	Fail Conditions
`create`	`git worktree add <path> [branch]`, `-b` for new branches	Path exists, branch is current
`list`	Parses `git worktree list` output into structured data	No git repo present
`switch`	Changes cwd to target worktree path	Already there, uncommitted changes in source
`remove`	`git worktree remove <path>`	Target is main repo, uncommitted changes

Edge Cases

Nested worktrees: Not supported by git — surface native error
Detached HEAD: Use path for identification instead of branch name
Untracked files on removal: Suggest removing/moving them first
Same-branch worktrees: Let git handle it, surface the error

Rollout Phases

Core tools (create, list, switch, remove) with error handling
/worktree interactive command with picker + back-switching
Session integration hooks (branch display, new session offer)
Polish: edge cases, README, user testing

2.5 KiB Raw Blame History