galaxy/specs/APP-3704/PRODUCT.md

Save Current Tab as New Config — Product Spec

Linear: APP-3704 Figma: House of Agents — node 7123-32864

Summary

Add a "Save as new config" item to the tab right-click context menu that snapshots the current tab's pane layout (splits, working directories, focus, and color) and writes it as a new tab config TOML file in ~/.warp/tab_configs/.

Problem

Users can create complex pane layouts interactively (splits, different working directories per pane, tab color) but have no way to persist that layout as a reusable tab config. The only path today is to hand-author TOML from scratch, which requires understanding the schema and manually transcribing the layout.

Goals

• Let users save their current tab's pane layout as a new tab config TOML with one click.
• Preserve the full spatial structure: splits, working directories, focus state, and tab color.
• Open the generated file in the user's editor so they can rename it and customize further.
• The saved config appears immediately in the + tab menu (the filesystem watcher picks it up).

Non-goals

• "Save and update config" (overwriting an existing tab config the tab was opened from). This requires tracking the source config path per tab and is a separate ticket.
• "Combine panes into single tab" — shown greyed out in the Figma, separate feature.
• Saving non-terminal pane content (notebooks, code panes, settings panes). These are not replayable from a TOML config.
• Parameterization. The saved config has no [params] section; the user can add params manually.

Figma

Figma: House of Agents — node 7123-32864

The updated tab right-click menu adds a new section between the "close" section and the "color" section:

• Save as new config — saves the current tab as a new tab config TOML.

Note: The Figma also shows "Save and update config" and "Combine panes into single tab" in this section. Those are out of scope for this ticket (see Non-goals).

User Experience

Triggering the save

1. User right-clicks a tab.
2. The context menu includes "Save as new config" (between the close-tab section and the color section). This item is only visible when the TabConfigs feature flag is enabled.
3. User clicks "Save as new config".

What happens

1. Warp snapshots the tab's pane tree: split directions, each pane's current working directory, focus state, and tab color.
2. Warp writes a new .toml file to ~/.warp/tab_configs/ with an auto-generated filename (my_tab_config.toml, or my_tab_config_1.toml if the name is taken).
3. Warp opens the file in the user's configured editor (same behavior as "Create new tab config...").
4. The filesystem watcher picks up the new file, and it appears in the + tab menu as "New Tab: My Tab Config".

TOML structure

The saved config uses the flat [[panes]] schema from APP-3575. Example for a two-pane horizontal split:

name = "My Tab Config"
color = "blue"

[[panes]]
id = "p1"
split = "horizontal"
children = ["p2", "p3"]

[[panes]]
id = "p2"
type = "terminal"
cwd = "/Users/me/project-a"
is_focused = true

[[panes]]
id = "p3"
type = "terminal"
cwd = "/Users/me/project-b"

Non-terminal pane handling

When the tab contains non-terminal panes (notebook, code, settings, etc.), those panes are replaced with an empty terminal pane in the saved config. This preserves the spatial layout (splits are maintained) while substituting content that cannot be replayed from TOML. The replacement terminal pane has no cwd set (omitted from TOML; defaults to the user's home directory when opened).

Tab title and color

• If the tab has a custom title, it is saved as the title field.
• If the tab has a color, it is saved as the color field.
• The config name is always "My Tab Config" — the user can rename it in the file.

Error handling

• If writing the file fails (permissions, disk full), a warning is logged and no file is opened. No toast or modal is shown — this is a low-probability error.

Success Criteria

1. Right-clicking a tab with FeatureFlag::TabConfigs enabled shows "Save as new config" in the context menu.
2. Clicking "Save as new config" on a single-pane terminal tab writes a valid TOML with one [[panes]] entry and the correct cwd.
3. Clicking "Save as new config" on a two-pane horizontal split writes a TOML with a split root and two leaf children with correct cwds.
4. Clicking "Save as new config" on a tab with a blue color writes color = "blue" in the TOML.
5. The focus state is preserved: the focused pane has is_focused = true; unfocused panes omit the field entirely.
6. A tab with a non-terminal pane (e.g., a notebook pane in a split) produces a TOML that replaces the notebook with a terminal pane, preserving the split.
7. The written TOML file round-trips: toml::from_str::<TabConfig>(toml::to_string_pretty(&config)) produces the same TabConfig.
8. The file appears in the + menu after saving.
9. Opening the saved config from the + menu reproduces the original pane layout.
10. The menu item does not appear when FeatureFlag::TabConfigs is off.

Validation

• Unit tests: tab_config_from_pane_snapshot for single pane, split, 2x2 grid, non-terminal replacement, focus handling, and TOML round-trip.
• Manual testing: Right-click → "Save as new config" on various tab layouts, verify the TOML, open the config from the + menu, confirm the layout matches.

Open Questions

(None outstanding.)