# Panes & Worktrees

<a id="creating-a-pane"></a>

Pane runs `git worktree add` when you create a pane and removes the worktree when you archive it, so you never type either command. Make one pane per feature. Reviews, fixes and QA for that feature run as [tabs](/docs/panels) in its pane.

> **Note:** A git worktree is a second checkout of the same repo in its own folder, on its own branch.

| You do | What happens |
| --- | --- |
| Press ⌘N, or click **+** on a repo's row in the sidebar | The **New Pane** dialog opens. Pick a **Base Branch** and Pane suggests a name. |
| Click **Create** | Pane creates the branch and its worktree in the background. |

The **+** next to the **Repositories** heading adds a repo instead.

<PaneCreator />

## What isolation means

- **No shared files.** Each pane writes to its own folder, so edits in one never overwrite another. This isn't a sandbox: an agent can still reach another folder by path.
- **Separate `.env`.** Each worktree reads its own environment file. [Worktree File Sync](/docs/configuration#worktree-file-sync) copies `.env` and other gitignored files into new worktrees.
- **Independent branches.** Merging one pane to main doesn't affect any other pane.

## Sidebar status cues

- **Pinned panes stay newest first.** A pane you pin goes to the top.
- **Cycling stays scoped.** Open a pane from Pinned and <KeyCombo keys={["⌘", "↑/↓"]} /> moves through pinned panes. Open from Repositories and it follows repository order.
- **A pane's name pulses** while an agent in it is working.
- **A dashed blue underline** marks a pane that finished while you were elsewhere, until you click into it.
- **Sections collapse.** Click Pinned or Repositories to hide that list.

## Archive or delete a pane

Neither one deletes your branch.

**Archive** (⌘⇧W, then confirm) stops the pane's agents, runs the project's archive script if it has one, and removes the worktree folder. Restore it any time, and Pane recreates the worktree from the branch. Terminal output is kept until 21 days after you last viewed the pane, then restored panes come back with empty terminals.

> **Warning:** Archiving from the app removes the worktree with any uncommitted changes in it. Commit and push first.

`runpane panes archive --pane <id> --yes`, which agents use, refuses when there's uncommitted, untracked or unpushed work, a busy agent, or unsent text in a tab. `--force` skips the check. A branch whose pull request merged counts as pushed.

**Permanently delete** appears on archived panes. It deletes the pane's record, terminal history and pasted files for good.

<Toggle title="How worktree paths work">
By default, a pane named `add-login` in `~/code/myapp` lives at `~/code/myapp/worktrees/add-login`. Change it with the project's **Worktree Folder**: a folder name inside the repo or a full path anywhere.
</Toggle>

<Toggle title="After a restart">
Pane brings back your panes, tabs, layout and terminal output. If agents were running when Pane quit, **Resume Previous Panes** lists them with checkboxes: **Resume All**, untick some for **Resume Selected**, or **Skip**. Each tab relaunches with its agent's resume command. OpenCode resumes once it has reported its conversation ID. Custom commands need a resume template.

Agent processes don't survive Pane quitting. To keep agents running while your laptop is closed, use a [Remote Pane](/docs/remote-daemon) host.
</Toggle>

<Toggle title="Adopted worktrees">
Pane can adopt worktrees you made with `git worktree add` or another tool. Archiving one leaves its folder on disk, since Pane didn't create it. Add `--remove-worktree` to `runpane panes archive` to remove it, which refuses on unpushed or uncommitted work.
</Toggle>
