Creating a worktree

Everything Pragma does starts from a worktree. This page covers the whole left sidebar: the creation dialog, fanout mode, and every affordance on a worktree row.

The worktree tree

The sidebar lists the selected project's worktrees:

• main first, then children. Nested worktrees render indented under their parent with expand/collapse carets.
• Each row shows an agent status dot (aggregate of the worktree's tabs) and, once a worktree is merged or its PR merged, a merge glyph instead of the branch glyph.
• Hold ⌘Ctrl to see 1…9 number badges and jump straight to a worktree.
• Hovering a non-main row reveals three actions: Pin, New child, and Delete worktree.
• Rows are detailed by default: under the title line a worktree shows its open pull request (a GitHub mark with the PR number), any git action in progress (Committing, Writing commit message, Committing & drafting PR, Drafting PR, Pushing, Opening PR, Merging, then briefly whether it succeeded), Ready for PR once a pull request has been drafted but not yet opened, and one line per agent — click anywhere on the card to select the worktree, or on an agent line to open its tab.
• Each agent line shows its status — Running, Needs input, or Finished — and a progress bar in the same yellow / red / green as the status dots. The bar always shows at least 10%. With a System 1 model configured, a running agent's status becomes what it is doing — Planning, Exploring, Coding, Testing, Debugging, Verifying, Reviewing, Documenting, Waiting, or Wrapping up — and the bar follows an estimate Pragma refreshes every time the agent writes a new message.
• Settings → Sidebar → Compact rows folds every row back to its title line; nesting, the title, and the status dot are the same in both layouts.

Right-click a row for the full menu: Rename · Pin / Unpin · Copy worktree path · Copy branch name · Open in editor (VS Code, Cursor, Windsurf, Zed, Sublime Text, IntelliJ IDEA, or the file explorer) · Hide · Delete.

Creating a single worktree

Click New worktree off main at the top of the sidebar (or New child on a row to branch from that worktree instead of main). The dialog:

Submit with Create worktree or ⌘↵Ctrl+↵ — the shortcut works from any field.

While the prompt is just a slash and a name, a picker under the cursor lists the agent's slash commands — its built-ins plus your project and user commands and skills. ↑/↓ and Enter or Tab pick one; Esc closes it. Shift+Tab in the prompt cycles the agent's modes (opencode's Build and Plan, a Claude Code agent), and the dropdown next to it sets the permission mode. Either control is hidden when the agent offers only one choice. Both start at the agent's default, and Pragma remembers the last permission mode per agent.

In Fan out the picker lists only the slash commands every attempt's agent has, and the prompt goes to each attempt as written, so a leading /command runs in all of them. Modes and permission modes are not offered there; each attempt starts in its agent's default. Type @ in either mode to attach files, issues, or pull requests — see Prompt context.

While it creates, a full-frame progress screen walks through Syncing base (when you accepted the sync offer), Creating worktree, and Running scripts when the project defines setup commands in .pragma/scripts.json. A failure before the worktree exists offers Dismiss; a later failure offers Retry.

Creation never blocks the workspace. Click any worktree row — including the one you are already on — to return to your terminal; the sidebar keeps a spinner row where the new worktree will land, and clicking that row brings the progress screen back. If you are still watching when it finishes, the new worktree takes over with its terminal or agent session; if you left, the session starts in the background and stays out of your way until you open the tab.

Reusing a previous prompt

The clock-shaped History button next to the Standard | Fan out switch swaps the form for the project's submitted runs, newest first: each shows its display title (or branch) with the prompt's first sentence under it. Click one to fill the dialog back out as it was sent — branch, title, prompt, and the agent and model, or every attempt row for a fanout. Nothing starts until you submit again. Only runs with a prompt are kept, and the history lives in this desktop app's local storage.

Syncing main first

If main is behind its remote, a Main is behind remote alert asks whether to sync before creating. Sync first for up-to-date branches, or create without syncing — for example when you are deliberately branching off an older base.

Fan out

One prompt, several isolated attempts, keep the winner. Switch the dialog to Fan out:

• Each attempt row has its own agent and model selection. Mix and match — try the same task on two agents, or two models on one agent. There is no attempt-count ceiling; two is the minimum.
• The branch field is always required: Pragma creates a fresh coordination parent worktree branched from where you opened the dialog. Attempts branch under it, each from the same captured base commit — so their diffs are directly comparable.
• Submit with Create & Fanout.

Attempts group under the parent in the sidebar, labelled by harness and model, each with its own status dot. The parent row carries a fanout indicator that opens the comparison.

Comparing attempts

Compare implementations (toolbar, with the fanout parent selected) replaces the workspace with a column per attempt:

• Scratchpads — the attempts' scratchpads paired across columns.
• Agent sessions — every column is a real, interactive terminal.
• Code — each attempt's diff against the shared base commit, deletions red and insertions green.

Resize columns; pick nothing until you have looked around. On a phone the same comparison is a pager, one attempt per page — see Fanouts on the phone.

Keeping a winner

Pick this implementation (or Pick implementation on an attempt's toolbar) opens the Keep {attempt}? dialog. Pragma will:

1. Commit any uncommitted winner work under an AI-generated message.
2. Merge the winner into the parent worktree.
3. Promote the winner's scratchpads to the parent.
4. Stop sessions and delete every attempt — the winner included.

This cannot be undone. A merge conflict stops before anything is deleted and leaves every attempt in place; a merge failure parks the fanout so you can retry the finalization. You can also pragma-cli fanout pick --member <member-id> from a terminal — agents do this too, via their skill.

Other fanout actions: Retry relaunches a failed attempt in its existing worktree, Cancel keeps the checkouts and marks the fanout cancelled.

Pinned worktrees

Pin the worktrees you keep coming back to:

• Pin appears on row hover and in the context menu.
• Pinned rows are promoted to the top, newest pin first, separated from the tree by a separator.
• A filled pin glyph on the row unpins on click.

Pins are per user (stored locally), not checked into the repo.

Renaming, hiding, deleting

• Rename — double-click a row (or the context menu). Enter commits, Escape cancels. Renaming changes the display title only; the branch keeps its name.
• Hide — tucks a finished worktree out of the way. Hidden worktrees are listed under a collapsible "Show N hidden" section with a per-row Show worktree button.
• Delete — removes the checkout. Refuses when the worktree has uncommitted changes unless you force it. Project teardown scripts run first and can veto the deletion by failing. Optionally delete the branch too.

Ports and scratchpads cards

Below the tree, the sidebar shows two cards when they have content:

• Ports — open TCP listeners grouped by worktree and terminal tab; click to focus the tab that owns the process. Only processes started from Pragma terminals are listed.
• Scratchpads — the selected worktree's agent-authored documents. See Scratchpads.