Configure iTerm2 workspace layouts with TOML-based configuration. Use when user mentions iTerm2 layout, workspace tabs, layout.toml, AutoLaunch script, or configuring terminal workspaces.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
Configure iTerm2 workspace layouts with proper separation of concerns: private paths in TOML config, publishable code in Python script.
Invoke this skill when user mentions:
| File | Location | Purpose |
|---|---|---|
| Config (private) | ~/.config/iterm2/layout.toml | User's workspace paths |
| Script (public) | ~/scripts/iterm2/default-layout.py | Layout logic |
| Template | ~/scripts/iterm2/layout.example.toml | Example config |
# ~/.config/iterm2/layout.toml
[layout]
left_pane_ratio = 0.20 # 0.0 to 1.0
settle_time = 0.3 # seconds
[commands]
left = "br --sort-by-type-dirs-first"
right = "zsh"
[worktrees]
# Optional: Enable git worktree discovery
# alpha_forge_root = "~/projects/alpha-forge"
# worktree_pattern = "alpha-forge.worktree-*"
[[tabs]]
name = "home"
dir = "~"
[[tabs]]
name = "projects"
dir = "~/projects"
[[tabs]]
dir = "~/Documents" # name defaults to "Documents"
# 1. Ensure config directory exists
mkdir -p ~/.config/iterm2
# 2. Copy template
cp ~/scripts/iterm2/layout.example.toml ~/.config/iterm2/layout.toml
# 3. Edit with your workspace paths
# Add [[tabs]] entries for each workspace
# 4. Restart iTerm2 to test
Add a [[tabs]] entry to ~/.config/iterm2/layout.toml:
[[tabs]]
name = "MyProject" # Tab display name (optional)
dir = "~/path/to/project"
Name field:
Delete or comment out the [[tabs]] entry:
# [[tabs]]
# name = "OldProject"
# dir = "~/old/project"
| Section | Key | Type | Default | Description |
|---|---|---|---|---|
[layout] | left_pane_ratio | float | 0.20 | Left pane width (0.0-1.0) |
[layout] | settle_time | float | 0.3 | Wait after cd (seconds) |
[commands] | left | string | br... | Left pane command |
[commands] | right | string | zsh | Right pane command |
[worktrees] | alpha_forge_root | string | null | Worktree root (optional) |
[worktrees] | worktree_pattern | string | .worktree- | Glob pattern |
[[tabs]] | dir | string | required | Directory path |
[[tabs]] | name | string | basename | Tab display name |
Symptom: Script Console shows error about missing config
Solution:
# Create config from template
cp ~/scripts/iterm2/layout.example.toml ~/.config/iterm2/layout.toml
Symptom: Script Console shows TOML parse error
Solution:
python3 -c "import tomllib; tomllib.load(open('~/.config/iterm2/layout.toml', 'rb'))"Symptom: iTerm2 opens but no custom tabs created
Causes:
[[tabs]] entries in configSolution:
# Verify config location
ls -la ~/.config/iterm2/layout.toml
# Verify AutoLaunch symlink
ls -la ~/Library/Application\ Support/iTerm2/Scripts/AutoLaunch/
# Check Script Console for errors
# iTerm2 > Scripts > Manage > Console
Symptom: Tab skipped with warning in Script Console
Solution: Verify directory path exists or create it:
mkdir -p ~/path/to/missing/directory
The script uses "print + early return" pattern:
Viewing errors: Scripts > Manage > Console in iTerm2
Enable dynamic tab creation for git worktrees:
[worktrees]
alpha_forge_root = "~/eon/alpha-forge"
worktree_pattern = "alpha-forge.worktree-*"
How it works:
~/eon/alpha-forge.worktree-* directoriesgit worktree listAF-ssv for sharpe-statistical-validation)