# Configuration

A `pane.json` tells Pane what to run for every new [pane](/docs/panes-and-worktrees): install dependencies, start the dev server, clean up on archive. Without it, you run `npm install` in each new worktree yourself.

## pane.json

Drop a `pane.json` in your project root. Commit it to share it with your team.

```json
{
  "scripts": {
    "setup": "npm install",
    "run": "npm run dev",
    "archive": "npm run cleanup"
  }
}
```

- **setup**: runs once when a new worktree is created
- **run**: runs when you press Play, or <KeyCombo keys={["⌘", "⇧", "D"]} /> (<KeyCombo keys={["Ctrl", "⇧", "D"]} /> on Windows and Linux)
- **archive**: runs when you archive the pane, before Pane removes its worktree

Pane reads `pane.json` from each pane's worktree, so a branch can test a change to it before merging.

<Toggle title="Other config formats (conductor.json, .gitpod.yml, devcontainer.json)">

Pane auto-detects config files in this order and uses the first one with a script:

1. `pane.json`
2. `conductor.json` (same format as `pane.json`)
3. `.gitpod.yml` (first task's `init` for setup, `command` for run)
4. `.devcontainer/devcontainer.json` (`postCreateCommand` for setup, `postStartCommand` for run)

</Toggle>

## Project Settings

Open the project's menu in the sidebar and choose **Project settings**.

- **Worktree Folder**: where this project's worktrees go. A folder name inside the repo (default `worktrees`) or a full path.
- **Open IDE Command**: the command Pane uses to open the worktree in your editor.
- **Build Script**, **Run Commands** and **Archive Script**: your own `setup`, `run` and `archive`.
- **Environment Variables**: see [Project environment variables](/docs/environment-variables#project-environment-variables).

> **Note:** A script set here beats `pane.json` on every branch. It stays on this computer; move it with **Settings → Import & Export**.

You don't set a main branch. Pane reads your remote's default branch (`origin/HEAD`). If that isn't set, it tries `origin/main`, `origin/master`, `main` and `master`, in that order. Need a different base for one pane? Pick it in the **Base branch** dropdown when you create the pane.

<a id="notifications"></a>Notification options are in [Settings → Notifications](/docs/settings#notifications).

## Worktree File Sync

Gitignored files like `.env` are automatically copied into every new worktree, so your pane is ready to run the moment it's created.

<FileSyncPreview />

<Toggle title="Sync details">

Out of the box, Pane copies these into every new worktree:

- `.env*` files
- agent config folders and files: `.claude`, `.codex`, `.cursor`, `.pi`, `.continue`, `.windsurf`, `.amazonq`, `.roo`, `.cline`, `.gemini`, `.junie` and `.aider.conf.yml`
- `node_modules`, last, so your credentials and config land first

Change the list in **Settings → Worktrees & Git → New worktrees → Files and directories**. Committed files don't need this, because git already puts them in the worktree.

Files sync once. If you change `.env` later, copy it from a new terminal tab in the pane:

```bash
cp "$(git worktree list --porcelain | head -1 | cut -d' ' -f2-)/.env" .
```

</Toggle>
