From e2b64b6ef8c463c1fd49a5711b3295291ccf051f Mon Sep 17 00:00:00 2001
From: Ben Holmes <bholmesdev@gmail.com>
Date: Wed, 2 Sep 2026 23:00:46 -0400
Subject: [PATCH] Document tab groups in launch configurations

Co-Authored-By: Warp <agent@warp.dev>
---
 .../sessions/launch-configurations.mdx        | 40 +++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/src/content/docs/terminal/sessions/launch-configurations.mdx b/src/content/docs/terminal/sessions/launch-configurations.mdx
index d6c56046c..78a1d25ee 100644
--- a/src/content/docs/terminal/sessions/launch-configurations.mdx
+++ b/src/content/docs/terminal/sessions/launch-configurations.mdx
@@ -24,6 +24,8 @@ You can create Launch Configurations in the app or by adding a YAML file.
 3. Name the configuration file. The name field cannot be empty.
 4. Click the Save configuration button.
 
+Warp saves each tab group's name, color, collapsed and pinned states, and tab membership.
+
 ### With a YAML File
 
 * Launch Configurations files are generated when you create them with the UI and can also be created or modified manually.
@@ -148,6 +150,44 @@ windows:
         color: green
 ```
 
+### Tab groups
+
+Use `tab_groups` on a window to define groups. Set `group` on each tab to the zero-based position of its group in the `tab_groups` list. Tabs without `group` open outside a group.
+
+Each tab group supports:
+
+* **`name`** - The group name.
+* **`color`** - One of `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, or `white`.
+* **`collapsed`** - Whether the group opens collapsed. Defaults to `false`.
+* **`pinned`** - Whether the group opens pinned. Defaults to `false`.
+
+```yaml title="grouped-development.yaml"
+---
+name: Grouped development
+windows:
+  - tabs:
+      - title: API
+        layout:
+          cwd: /Users/warp-user/Projects/api
+        group: 0
+      - title: Tests
+        layout:
+          cwd: /Users/warp-user/Projects/api
+          commands:
+            - exec: npm test
+        group: 0
+      - title: Notes
+        layout:
+          cwd: /Users/warp-user/Documents
+    tab_groups:
+      - name: Backend
+        color: blue
+        collapsed: false
+        pinned: false
+```
+
+Tabs in the same group must be adjacent in the `tabs` list. Warp opens a tab outside a group when its `group` index does not exist or when the same group appears again after a different group or ungrouped tab. Warp does not create groups without member tabs.
+
 ### Panes
 
 Launch Configurations support setting split panes in each tab. Note that Warp also supports nesting split panes in launch configuration files.