Worktrees
Ghostex treats Git worktrees as first-class sidebar projects nested under their parent repository. Each worktree gets its own session group, git menu (including Sync with Main), and commit review flow — while sharing the parent's Actions list.
What it is
A worktree project is a linked Git checkout registered in Ghostex under its main repository. Worktrees appear as child rows in the sidebar, ordered by orderProjectsWithWorktrees. There is no separate Switch worktree command — click the worktree row to focus it.
Worktree headers show Create PR instead of Add Worktree. Git actions always open the commit review modal before commit, push, or PR.
Add Worktree modal
| Option | What it does |
|---|---|
Add Worktree | Modal title and project header tooltip |
Create New | Mode — new branch checkout with agent launch |
Open Existing | Mode — register an already-created Git worktree |
Agent | Agent picker for Create New |
First prompt | Optional initial prompt (+ Add Images picker) |
New Worktree | Submit button for Create New |
Existing worktree | Select field for Open Existing |
Open Worktree | Submit button for Open Existing |
Create New workflow
- Click Add Worktree on a main project header → modal opens.
- Pick Agent and optional First prompt (images supported via native picker).
- Submit New Worktree → gxserver creates checkout, runs optional setup command, registers worktree project.
- Agent session launches with the first prompt in the new worktree directory.
- New worktree appears nested under parent; parent's Show less state activates.
Open Existing workflow
- Switch modal to Open Existing → gxserver runWorktreeAction { action: list } loads Git worktrees.
- Select an existing worktree → Open Worktree → gxserver addProjectPath registers or focuses it.
- No agent launch — use this when the worktree folder already exists on disk.
- If the path is already registered, Ghostex focuses the existing sidebar row.
Merge to main
Two merge paths from a worktree:
- Direct — Git commit review modal → Merge to main → confirm → gxserver commits selected files, checks out parent main, merges branch. Toast: Worktree merged to main.
- Agent — Create PR or Multicommit & Release / Release from the git menu → agent handles commits, push, PR, and optional cleanup.
- Sync with Main (worktree-only agent workflow) — brings main into the worktree before merging back.
Commit modal checkbox: Delete worktree project after this action finishes.
Delete and cleanup
| Option | What it does |
|---|---|
Delete Worktree | Context menu — full git cleanup with confirmation modal |
Remove Worktree | Context menu — removes sidebar row without full git cleanup |
Delete Worktree (button) | Confirm in delete modal |
Commit (in delete modal) | Dirty worktree shortcut → commit review modal |
Delete local branch | Optional checkbox in delete modal (unchecked by default) |
Delete remote branch | Optional checkbox in delete modal (unchecked by default) |
Clean worktrees show: The worktree has no local changes. Running toast: Deleting worktree.
Project settings
Settings → Projects → per main project (worktree projects inherit from parent):
| Option | What it does |
|---|---|
worktreeCommand | Shell command run in the new worktree folder before the project is added (e.g. bun install). Persisted via gxserver gitConfig.worktreeCommand. |
Save Command / Clear | Persist or remove the setup command for the selected main project |
Project board integration
Kanban ticket dialogs offer Start work with a location selector:
| Option | What it does |
|---|---|
Current project | Launch agent in the main repository |
New worktree | Create worktree checkout and launch agent there |
Create & Start uses the same location picker. Default Prompt Agent from Settings drives the launched session.
Tips
- Set worktreeCommand to bun install or cp .env.example .env so new worktrees boot cleanly.
- Use Open Existing when you created worktrees with plain git worktree add outside Ghostex.
- Sync with Main before Merge to main when main has moved since you branched.
- Remove Worktree is lighter than Delete Worktree — use Remove when the folder is already gone.
- Drag-reorder worktrees within their parent family; cross-parent moves are not supported.