Warp Tab Config Reference

tab-configs

This skill is the canonical reference for Warp tab config TOML files.

Tab configs live under ~/.warp/tab_configs/ for standard Warp builds. Non-stable builds (e.g. Preview or pre-release channels) use a channel-specific variant such as ~/.warp-<channel>/tab_configs/. Do NOT use ~/Library/Application Support/ — that is the wrong location.

To find the active data directory, inspect which ~/.warp* directories exist on the user's machine. Each .toml file defines a single tab layout that appears in the + menu. When the user selects one, Warp opens a new tab with the configured pane layout and runs any specified commands.

Use this skill as shared context:

• create-tab-config should use it when authoring a new config.
• update-tab-config should use it when modifying an existing config.
• If this skill is invoked directly for a creation or editing task, follow the same guidance below.

Guidance before writing or editing

• If the request is missing important details, use the ask_user_question tool instead of guessing. Clarify things like:
  • whether the user wants a new config or wants to edit an existing one
  • the desired pane layout
  • directories, commands, and which pane should be focused
  • whether parameters are needed
• Use descriptive pane IDs such as "editor", "server", or "top_left" instead of generic names like "pane1".
• Use snake_case file names for new configs.
• When creating or locating tab configs, use the correct tab config directory for the user's current Warp build/channel rather than hardcoding a single base directory.
• If updating an existing config, read the file first and preserve user structure where possible.

Schema Reference

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".

Pane list

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

Leaf node fields

• id (required, string): Unique identifier.
• 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. Applies to terminal and agent types.
• commands (optional, array of strings): Commands to run in sequence on open. Applies to terminal and agent types.
• is_focused (optional, bool): Set true on at most one pane to give it initial focus.
• shell (optional, string): Shell executable to open this pane in (e.g. "pwsh", "zsh", "bash", "fish"). Only applies to terminal and agent types. If omitted or the shell is not installed, the user's default shell is used.

Split node fields

• id (required, string): Unique identifier for this node.
• 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 IDs. Must have 2+ entries. Order = visual order.

[[panes]]
id = "server"
type = "terminal"
directory = "~/code/backend"
commands = ["cargo watch -x run"]