` 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.
On Warp Preview, use `warppreview://tab_config/` 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](https://funcoding.ai/agents/warp/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.
Commands in the `commands` array run in sequence, with each command waiting for the previous one to finish. A long-running or interactive command like `ssh` never returns control to the shell, so any commands listed after it don't run in the session. To run commands on a remote host, include them in the `ssh` command itself (e.g., `ssh -t user@host 'cd ~/project && exec $SHELL -l'`).
#### 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.
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.]` 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:
```toml
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:
```toml
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:
```toml
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:
```toml
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)](https://funcoding.ai/agents/warp/terminal/sessions/launch-configurations/) — the previous session configuration format. Existing configs still work, but Tab Configs are the recommended approach for new setups.
* [Tabs](https://funcoding.ai/agents/warp/terminal/windows/tabs/) — tab management, keyboard shortcuts, and behavior settings
* [Themes](https://funcoding.ai/agents/warp/terminal/appearance/themes/) — customize the colors used by tab color settings
* [Working Directory](https://funcoding.ai/agents/warp/terminal/more-features/working-directory/) — how Warp resolves working directories
* [Third-party CLI agents](https://funcoding.ai/agents/warp/agents/cli-agents/overview/) — use the `"agent"` pane type to open tabs in Agent Mode
* [Warp URI Scheme](https://funcoding.ai/agents/warp/terminal/more-features/uri-scheme/) — open Tab Configs via `warp://tab_config/` deeplinks