> For the complete documentation index, see [llms.txt](/llms.txt).
> Markdown versions of each page are available by appending .md to any URL.

# Tab Configs

Tab Configs let you define reusable tab setups — including directory, startup commands, pane layout, shell, and theme — in a simple TOML file.

Tab Configs let you define reusable tab setups — including directory, startup commands, pane layout, shell, and theme — in a simple TOML file. Select a Tab Config from the `+` menu to open a fully configured tab with a single click.

![Tab Configs in Warp](https://i.ytimg.com/vi/Bq30S3wIpOU/sddefault.jpg)

## How Tab Configs work

Each Tab Config is a `.toml` file stored in Warp’s `tab_configs` directory. Every file defines a single tab layout with optional pane splits, startup commands, and parameterized inputs. Tab Configs appear in the `+` menu alongside your existing tabs, so you can launch a preconfigured workspace instantly.

The `tab_configs` directory lives in a different location on each platform:

-   [macOS](#tab-panel-830)
-   [Windows](#tab-panel-831)
-   [Linux](#tab-panel-832)

`~/.warp/tab_configs/` (Stable) or `~/.warp-preview/tab_configs/` (Preview).

`%APPDATA%\warp\Warp\data\tab_configs\` (Stable) or `%APPDATA%\warp\WarpPreview\data\tab_configs\` (Preview).

`${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/tab_configs/` (Stable) or `${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal-preview/tab_configs/` (Preview).

For the full list of Warp file locations, see [File and folder locations](/terminal/settings/file-locations/).

## Creating a Tab Config

### From the UI

1.  Click the **+** button in the tab bar to open the new-tab menu.
2.  Click **\+ New tab config**. Warp creates a new `.toml` file in the `tab_configs` directory and opens it for editing.

### Manually

1.  Create a new `.toml` file in the `tab_configs` directory shown above. Use snake\_case for the file name (e.g., `dev_server.toml`).
2.  Define the tab layout using the schema below, then save the file. The new config appears in the `+` menu automatically.

### Save an existing tab as a Tab Config

You can also capture a tab’s current state as a reusable Tab Config without writing TOML. Right-click any tab in the [vertical tabs](/terminal/windows/vertical-tabs/) panel or horizontal tab bar to open the context menu, then click **Save as new config**. Warp generates a `.toml` file from the tab’s layout, commands, and directory and adds it to the `+` menu.

![Tab context menu in Warp's vertical tabs panel with Save as new config highlighted](/_astro/save-new-tab-config.Dsmhq0Di_Z6Qgvd.webp?dpl=dpl_EiyqSkg4pHB6kfVMbE4HM9uh74qp)

Saving a tab config.

## Managing Tab Configs

Saved Tab Configs appear in the `+` menu for quick access. When you hover a Tab Config in the menu, a **sidecar panel** appears alongside it with options to:

-   **Edit config** — Open the underlying `.toml` file for manual editing. The editor also shows a footer to invoke the **update tab config** skill, so you can describe changes in natural language and have Warp’s agent apply them.
-   **Remove** — Remove the Tab Config from the `+` menu.
-   **Make default** — Assign the Tab Config as the default `Cmd+T` action for new tabs.

![Warp's + menu open with a saved screenshots_tab_config entry highlighted, and a sidecar panel showing Make default, Edit config, and Remove action buttons](/_astro/saved-tab-config-menu.DEhwYYBm_1kkNMq.webp?dpl=dpl_EiyqSkg4pHB6kfVMbE4HM9uh74qp)

Tab config menu with sidecar options.

## Open a Tab Config from a URL

You can open a saved Tab Config directly via Warp’s [URI scheme](/terminal/more-features/uri-scheme/). This is useful for browser bookmarks, scripts, and launchers like Raycast or Alfred that need to jump straight into a configured pane layout without going through the `+` menu.

By default, the Tab Config opens as a new tab in the active window. Pass `?new_window=true` (or invoke when no Warp window is open) to open it in a new window instead.

```
# Open my_tab.toml as a new tab in the focused windowopen "warp://tab_config/my_tab"
# Open it in a brand-new windowopen "warp://tab_config/my_tab?new_window=true"
```

`<name>` is matched case-insensitively against the file stem of the `.toml`, so `warp://tab_config/my_tab` and `warp://tab_config/my_tab.toml` both resolve to `my_tab.toml`. Matching uses the filename rather than the `name` field inside the file, because multiple Tab Configs can share the same display name.

If the Tab Config declares `[params.*]` entries, the params modal opens just like launching from the `+` menu. Worktree-style configs that reference `{{autogenerated_branch_name}}` still get a freshly generated branch name on each open.

Note

On Warp Preview, use `warppreview://tab_config/<name>` instead.

## Using skills to manage Tab Configs

Warp includes built-in skills for creating and modifying Tab Configs through natural language:

-   **Create Tab Config** — Generate a new Tab Config from a description (e.g., “create a 2x2 grid with one pane running my dev server”).
-   **Update Tab Config** — Modify an existing Tab Config by describing the changes you want.

To use these skills, type `/skills` in Agent Mode and select the tab config skill, or use the footer that appears when editing a Tab Config file.

## Tab Config TOML schema

### Top-level fields

-   **`name`** (required, string) — display name shown in the `+` menu.
-   **`title`** (optional, string) — custom tab title. Supports `{{param}}` template variables.
-   **`color`** (optional, string) — tab color. One of: `"black"`, `"red"`, `"green"`, `"yellow"`, `"blue"`, `"magenta"`, `"cyan"`, `"white"`. Actual color values are derived from your Warp [Theme](/terminal/appearance/themes/).

### Pane list

All panes are defined in a flat `[[panes]]` array. The first entry is the root of the pane tree. Each entry is either a **split node** (branch) or a **leaf node**.

#### Leaf node fields

-   **`id`** (required, string) — unique identifier for this pane. Use descriptive names like `"editor"` or `"server"`.
-   **`type`** (required, string) — `"terminal"` (standard shell), `"agent"` (opens in Agent Mode), or `"cloud"` (cloud mode pane, no local shell).
-   **`directory`** (optional, string) — initial working directory. Supports `~` expansion and `{{param}}` template variables.
-   **`commands`** (optional, array of strings) — commands to run in sequence when the tab opens.
-   **`shell`** (optional, string) — shell executable to use for this pane (e.g. `"pwsh"`, `"zsh"`, `"bash"`, `"fish"`). Only applies to `terminal` and `agent` pane types. If omitted or the specified shell is not installed, the user’s default shell is used.
-   **`is_focused`** (optional, bool) — set to `true` on at most one pane to give it initial focus.

#### Split node fields

-   **`id`** (required, string) — unique identifier for this split.
-   **`split`** (required, string) — `"horizontal"` (children arranged left-to-right) or `"vertical"` (children arranged top-to-bottom).
-   **`children`** (required, array of strings) — ordered list of child pane `id` values. Must contain at least 2 entries. Order determines visual order.

Note

All children within a split are equally sized. There are no flex or proportion values.

### Parameters

Parameters let users fill in values at open time via a modal prompt. Declare them with `[params.<name>]` tables and reference them in `directory`, `commands`, and `title` using `{{name}}` syntax.

Each parameter has:

-   **`type`** (optional, string) — `"text"` (default, freeform input), `"branch"` (Git branch picker), or `"repo"` (repository picker).
-   **`description`** (optional, string) — label shown in the fill-in UI.
-   **`default`** (optional, string) — default value.

`{{autogenerated_branch_name}}` is a reserved template variable. If a Tab Config references it, Warp generates a unique worktree branch name on each open instead of prompting the user.

## Examples

### Single pane

A simple config that opens a terminal in a project directory and starts a dev server:

```
name = "Dev Server"
[[panes]]id = "main"type = "terminal"directory = "~/code/my-app"commands = ["npm run dev"]
```

### Two panes side by side

An editor and server running in parallel, with the editor focused:

```
name = "Editor + Server"color = "green"
[[panes]]id = "root"split = "horizontal"children = ["editor", "server"]
[[panes]]id = "editor"type = "terminal"directory = "~/code/my-app"commands = ["nvim ."]is_focused = true
[[panes]]id = "server"type = "terminal"directory = "~/code/my-app"commands = ["npm run dev"]
```

### Cross-shell development

A config that opens two panes side by side, each with a different shell:

```
name = "Cross Shell"color = "cyan"
[[panes]]id = "root"split = "horizontal"children = ["bash_pane", "pwsh_pane"]
[[panes]]id = "bash_pane"type = "terminal"shell = "bash"directory = "~/code/my-app"is_focused = true
[[panes]]id = "pwsh_pane"type = "terminal"shell = "pwsh"directory = "~/code/my-app"
```

### Worktree with parameters

A parameterized config that creates a new Git worktree on open:

```
name = "New Worktree"title = "{{branch_name}}"
[[panes]]id = "main"type = "terminal"directory = "{{repo}}"commands = [  "git worktree add -b {{branch_name}} ../{{branch_name}} {{base_branch}}",  "cd ../{{branch_name}}",]
[params.repo]type = "repo"description = "Repository path"
[params.base_branch]type = "branch"description = "Base branch to branch from"
[params.branch_name]type = "text"description = "New branch name"default = "my-feature"
```

### Quick worktree setup

You can also create a worktree-based Tab Config directly from the `+` menu by clicking **New worktree config** and selecting the repo you want your worktree to be from. Warp generates the Tab Config automatically and saves it for future use.

## Related pages

-   [Launch Configurations (Legacy)](/terminal/sessions/launch-configurations/) — the previous session configuration format. Existing configs still work, but Tab Configs are the recommended approach for new setups.
-   [Tabs](/terminal/windows/tabs/) — tab management, keyboard shortcuts, and behavior settings
-   [Themes](/terminal/appearance/themes/) — customize the colors used by tab color settings
-   [Working Directory](/terminal/more-features/working-directory/) — how Warp resolves working directories
-   [Third-party CLI agents](/agent-platform/cli-agents/overview/) — use the `"agent"` pane type to open tabs in Agent Mode
-   [Warp URI Scheme](/terminal/more-features/uri-scheme/) — open Tab Configs via `warp://tab_config/<name>` deeplinks