tab-configs

name	tab-configs
description	Reference the CastCodes tab config schema, validation rules, and examples. Use when creating or updating CastCodes tab config TOML files or when another tab-config skill needs the canonical schema details.

tab-configs

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

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

To find the active data directory, inspect which ~/.cast-codes* 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, CastCodes 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 CastCodes 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"]

Sizing

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 UI. Declare them with [params.<name>] tables. Reference them in directory, commands, and title with {{name}} syntax.

{{autogenerated_branch_name}} is a special-cased reserved template variable: if a tab config references it, CastCodes generates a unique worktree branch name on each open instead of prompting the user for that value.

Each parameter has:

• type (optional, string): "text" (default), "branch" (git branch picker), or "repo" (repo picker).
• description (optional, string): Shown in the fill-in UI.
• default (optional, string): Default value.

[params.project_dir]
type = "repo"
description = "Project directory"

[params.branch]
type = "branch"
description = "Branch to check out"

Validation rules

Ensure your output follows these rules:

• Every ID in a children array must reference an existing [[panes]] entry.
• No cycles in the pane tree.
• Leaf panes must NOT have children or split.
• Leaf panes must have a type field ("terminal", "agent", or "cloud").
• Split panes (have split) must have children with at least 2 entries.
• At most one pane may have is_focused = true.
• All id values must be unique across the file.
• The first [[panes]] entry is the root of the tree.

Examples

Single pane

name = "Dev Server"

[[panes]]
id = "main"
type = "terminal"
directory = "~/code/my-app"
commands = ["npm run dev"]

Two panes side by side

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

2x2 grid

name = "Full Stack"

[[panes]]
id = "root"
split = "horizontal"
children = ["left_col", "right_col"]

[[panes]]
id = "left_col"
split = "vertical"
children = ["frontend", "backend"]

[[panes]]
id = "frontend"
type = "terminal"
directory = "~/code/frontend"
commands = ["npm run dev"]
is_focused = true

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

[[panes]]
id = "right_col"
split = "vertical"
children = ["tests", "logs"]

[[panes]]
id = "tests"
type = "terminal"
directory = "~/code/backend"
commands = []

[[panes]]
id = "logs"
type = "terminal"
directory = "~/code/backend"
commands = ["tail -f logs/dev.log"]

Three-pane layout (1 left, 2 stacked right)

name = "Main + Side Stack"

[[panes]]
id = "root"
split = "horizontal"
children = ["main", "side_stack"]

[[panes]]
id = "main"
type = "terminal"
directory = "~/code/project"
commands = []
is_focused = true

[[panes]]
id = "side_stack"
split = "vertical"
children = ["top_right", "bottom_right"]

[[panes]]
id = "top_right"
type = "terminal"
directory = "~/code/project"
commands = []

[[panes]]
id = "bottom_right"
type = "terminal"
directory = "~/code/project"
commands = []

With parameters

CastCodes-generated worktree configs default to ~/.cast-codes/worktrees/<repo-name>/<worktree-name>. When writing a reusable config by hand, derive the repo-name segment at shell runtime with $(basename {{repo}}).

name = "New Worktree"
title = "{{branch_name}}"

[[panes]]
id = "main"
type = "terminal"
directory = "{{repo}}"
commands = [
  "git worktree add -b {{branch_name}} $HOME/.cast-codes/worktrees/$(basename {{repo}})/{{branch_name}} {{base_branch}}",
  "cd $HOME/.cast-codes/worktrees/$(basename {{repo}})/{{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"

Common patterns

When the user says... | Generate... "single pane" / "simple tab" | One [[panes]] leaf entry "split" / "side by side" / "two panes" | Horizontal split with 2 terminal children "top and bottom" / "stacked" | Vertical split with 2 terminal children "2x2" / "grid" / "four panes" | Horizontal split → 2 vertical splits → 4 terminals "run X" / "auto-run X" | Put X in the commands array "with claude" / "running claude" | commands = ["claude"] in the relevant pane "three panes" (no further detail) | Horizontal split: 1 terminal + 1 vertical split with 2 terminals