93 lines
5.5 KiB
Markdown
93 lines
5.5 KiB
Markdown
# Finalize TOML Schema for Tab Configs
|
|
|
|
Linear: [APP-3575](https://linear.app/warpdotdev/issue/APP-3575/finalize-toml-schema-for-tab-configs)
|
|
|
|
## Summary
|
|
|
|
Replace the recursive `[layout]` / `[[layout.panes]]` TOML nesting in tab configs with a flat `[[panes]]` array where nodes reference children by string ID. This makes deeply nested split layouts readable and hand-editable, and ships a bundled Oz skill so users can generate tab configs from natural language.
|
|
|
|
## Problem
|
|
|
|
The existing tab config layout format uses recursive TOML tables (`[[layout.panes]]`, `[[layout.panes.panes]]`, etc.). At depth 3+ this becomes unreadable and error-prone for hand-editing. Users who want a 2x2 grid or deeper nesting have to mentally track nested array-of-tables syntax, which is a significant barrier to adoption.
|
|
|
|
Additionally, there is no guided way for users to create tab configs — they must hand-author TOML from scratch.
|
|
|
|
## Goals
|
|
|
|
- A flat, ID-referenced pane tree format that supports arbitrarily deep nesting while remaining readable.
|
|
- A bundled Oz skill (`tab-configs`) that generates valid tab config TOML from natural language descriptions.
|
|
- A default template that is ready to use out of the box (single terminal pane, uncommitted, with `commands = []` pre-populated).
|
|
- Tab color support (`color` field) matching launch config parity.
|
|
|
|
## Non-goals
|
|
|
|
- Supporting non-terminal pane types beyond agent and cloud (notebook, code, settings, etc.).
|
|
- Multi-tab or multi-window configs (tab configs define a single tab by design).
|
|
- Proportional/flex sizing of children within a split.
|
|
- Converting existing launch configs to the new tab config format.
|
|
|
|
## Figma
|
|
|
|
Figma: none provided. This feature has no new UI — it changes the file format and adds an Oz skill.
|
|
|
|
## User experience
|
|
|
|
### Creating a new tab config
|
|
|
|
1. User clicks `+` → "Create new tab config..." in the tab bar menu.
|
|
2. Warp writes the default template to `~/.warp/tab_configs/my_tab_config.toml` and opens it in the user's configured editor.
|
|
3. The template contains an active single-pane config with `commands = []`, and commented-out examples for two-pane split, 2x2 grid, and parameterized configs.
|
|
4. The template header mentions the Oz skill: "Ask Oz to generate a tab config for you!"
|
|
|
|
### Using the Oz skill
|
|
|
|
- User invokes `/skills → tab-configs` or asks Oz naturally (e.g. "create me a 2x2 tab config with one pane running my dev server").
|
|
- Oz generates a valid `.toml` file and writes it to `~/.warp/tab_configs/`.
|
|
- The file immediately appears in the `+` menu (the filesystem watcher picks it up).
|
|
|
|
### Opening a tab config
|
|
|
|
- User clicks `+` → "New Tab: <config name>".
|
|
- If the config has `[params]`, a modal appears for the user to fill in values.
|
|
- Warp opens a new tab with the specified pane layout, running any configured commands.
|
|
- If the config has a `color` field, the tab gets that color.
|
|
|
|
### Format behavior
|
|
|
|
- Pane layout is defined with a flat `[[panes]]` array.
|
|
- The first `[[panes]]` entry is the root of the tree.
|
|
- Split nodes have `split` (horizontal/vertical) and `children` (ordered array of child IDs).
|
|
- Leaf nodes have `id`, required `type` (`"terminal"`, `"agent"`, or `"cloud"`), optional `cwd`, optional `commands`, and optional `is_focused`.
|
|
- `terminal` opens a standard shell session. `agent` opens a terminal in Agent Mode. `cloud` opens a cloud mode (ambient agent) pane with no local shell.
|
|
- `cwd` and `commands` apply to `terminal` and `agent` types; they are ignored for `cloud`.
|
|
- `worktree_name_autogenerated` (optional, bool, default false): when `true`, Warp auto-generates the worktree branch name instead of prompting the user. The app detects worktree configs by scanning `commands` for `git worktree`.
|
|
- All children within a split are equally sized.
|
|
- If no pane has `is_focused = true`, the first leaf pane gets focus automatically.
|
|
|
|
### Error handling
|
|
|
|
- If the flat pane tree has validation errors (missing child references, duplicate IDs, fewer than 2 children in a split), the config falls back to a single empty terminal pane and logs a warning.
|
|
- Invalid TOML or missing `name` field causes the file to be skipped with a warning logged.
|
|
|
|
## Success criteria
|
|
|
|
1. A tab config using the flat `[[panes]]` format with a horizontal 2-pane split opens correctly: two side-by-side terminal panes, each with the specified `cwd` and `commands`.
|
|
2. A tab config using the flat format with a 2x2 grid (horizontal split → two vertical splits → four terminals) opens correctly with four equal-sized panes.
|
|
3. A tab config with `color = "blue"` opens with a blue tab.
|
|
4. A tab config with `is_focused = true` on a specific pane gives that pane initial focus.
|
|
5. A tab config with no `is_focused` gives focus to the first (leftmost/topmost) leaf pane.
|
|
6. A tab config with `[params]` shows the param-fill modal before opening.
|
|
7. A tab config with a `[[panes]]` format that has an invalid child reference logs a warning and opens a single empty terminal pane.
|
|
8. The `tab-configs` bundled skill appears in `/skills` in Warp.
|
|
9. The default template, when uncommitted and left as-is, parses as a valid single-pane tab config named "My Tab Config".
|
|
|
|
## Validation
|
|
|
|
- Unit tests for parsing and rendering the flat format (single pane, split, 2x2, focus handling, error cases).
|
|
- Manual verification: create a 2x2 tab config TOML, open it from the `+` menu, confirm four panes appear with correct `cwd` and `commands`.
|
|
- Manual verification: invoke the `tab-configs` skill and confirm it generates a valid TOML file that opens correctly.
|
|
|
|
## Open questions
|
|
|
|
(None outstanding.)
|