iterm2-layout_skill

Overview

This skill configures iTerm2 workspace layouts using a TOML configuration and a lightweight Python script. It separates private user paths (kept in ~/.config/iterm2/layout.toml) from publishable layout logic (the script), enabling reproducible tab and pane setups and optional git worktree discovery. It includes AutoLaunch support so iTerm2 recreates your workspace on startup.

How this skill works

The Python script reads a TOML file that defines layout settings, pane commands, and a list of tabs with directories and optional names. It validates the config, creates tabs and split panes in iTerm2 via the Python API, and skips missing directories while logging warnings to the Script Console. Optionally the script can discover git worktrees by globs, validate them with git, and inject generated worktree tabs adjacent to their main project tab.

When to use it

• You want consistent iTerm2 tabs and pane layouts across sessions or machines.
• Setting up AutoLaunch so iTerm2 recreates a development workspace on startup.
• Managing many project tabs and preferring config-driven workspace definitions.
• Automatically discovering git worktrees and exposing each as its own tab.
• Sharing layout logic while keeping personal paths private.

Best practices

• Keep only machine-specific paths in ~/.config/iterm2/layout.toml and keep the script public-ready.
• Use explicit [[tabs]] entries for important workspaces; omit name to use basename.
• Set reasonable settle_time to allow shell directory changes to complete before running commands.
• Validate TOML with tomllib or a quick Python load after edits to catch syntax errors.
• Use AutoLaunch by placing the script symlink in iTerm2's Scripts/AutoLaunch folder for reliable startup behavior.

Example use cases

• Create a home tab, a projects tab, and a Documents tab automatically when iTerm2 starts.
• Auto-discover git worktrees under a mono-repo and open each as an abbreviated-named tab.
• Define left/right pane commands (e.g., file browser in left, zsh in right) and a left_pane_ratio.
• Provision a consistent terminal workspace across new machines by copying the TOML template and editing paths.
• Quickly add or remove project tabs by editing the TOML and restarting iTerm2.