Skip to main content
skill CX Codex

iterm2-layout — Claude Code skill: what it does, how to install

iterm2-layout configures iTerm2 workspace layouts, panes, and tabs using a TOML file. Helps an AI agent register project directories and auto-discover git worktrees.

MIT 126 installs ★ 3 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add terrylica/cc-skills --skill iterm2-layout -a claude-code
Open on GitHub

What iterm2-layout does

This skill manages iTerm2 workspaces by separating layout logic from user paths. Private workspace directories live in ~/.config/iterm2/layout.toml, while public orchestration logic runs from ~/scripts/iterm2/default-layout.py.

The TOML configuration sets split pane proportions via left_pane_ratio, command startup strings like br or zsh, and a post-navigation wait time (settle_time). It also supports glob-based git worktree auto-discovery, creating labeled tabs next to the main repo.

For automatic startup, iTerm2 needs a symlink in its AutoLaunch directory. Missing workspace paths trigger warnings in the iTerm2 Script Console rather than halting execution.

What it helps with

  • Configure split pane ratios and startup commands in iTerm2
  • Set up automatic tab discovery for git worktrees
  • Add or edit workspace paths inside ~/.config/iterm2/layout.toml
  • Validate TOML layout syntax via Python before restarting iTerm2

Example prompts for the agent

  • Add a new tab for ~/projects/analytics to ~/.config/iterm2/layout.toml
  • Configure git worktree detection for ~/projects/app in my iTerm2 layout
  • Check layout.toml for syntax errors using tomllib

How to install iterm2-layout

1Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill iterm2-layout -a claude-code

2Manually: put the files in place

~/.claude/skills/iterm2-layout/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/iterm2-layout/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about iterm2-layout

How to install iterm2-layout in Claude Code?

Run npx skills add terrylica/cc-skills --skill iterm2-layout -a claude-code.

What does iterm2-layout do?

It guides your agent in managing iTerm2 terminal tabs, pane ratios, and worktree detection via a TOML config file.

Where are the configuration files stored?

User paths reside in ~/.config/iterm2/layout.toml, while the layout script is placed at ~/scripts/iterm2/default-layout.py.

Source text

SKILL.md · MIT
---
name: iterm2-layout
description: Configure iTerm2 workspace layouts with TOML. TRIGGERS - iTerm2 layout, workspace tabs, layout.toml, AutoLaunch.
allowed-tools: Bash, Read, Edit
---

# iTerm2 Layout Configuration

<!-- ADR: /docs/adr/2025-12-15-iterm2-layout-config.md -->

Configure iTerm2 workspace layouts with proper separation of concerns: private paths in TOML config, publishable code in Python script.

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## When to Use This Skill

Use this skill when:

- Configuring iTerm2 workspace layouts
- Adding, removing, or modifying workspace tabs
- Setting up AutoLaunch scripts for iTerm2
- Configuring git worktree tab auto-discovery

## Configuration Overview

### File Locations

| 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 File Format

```toml
# ~/.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
# main_repo_root = "~/projects/my-project"
# worktree_pattern = "my-project.worktree-*"

[[tabs]]
name = "home"
dir = "~"

[[tabs]]
name = "projects"
dir = "~/projects"

[[tabs]]
dir = "~/Documents"  # name defaults to "Documents"
```

## Setup Instructions

### First-Time Setup

```bash
/usr/bin/env bash << 'CONFIG_EOF'
# 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
CONFIG_EOF
```

### Adding a New Tab

Add a `[[tabs]]` entry to `~/.config/iterm2/layout.toml`:

```toml
[[tabs]]
name = "MyProject"  # Tab display name (optional)
dir = "~/path/to/project"
```

**Name field**:

- If omitted, uses directory basename
- Custom names useful for abbreviations (e.g., "AF" instead of "research-repo")

### Removing a Tab

Delete or comment out the `[[tabs]]` entry:

```toml
# [[tabs]]
# name = "OldProject"
# dir = "~/old/project"
```

## Configuration Schema

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

## Troubleshooting

### Error: "Layout configuration not found"

**Symptom**: Script Console shows error about missing config

**Solution**:

```bash
# Create config from template
cp ~/scripts/iterm2/layout.example.toml ~/.config/iterm2/layout.toml
```

### Error: "Invalid TOML syntax"

**Symptom**: Script Console shows TOML parse error

**Solution**:

1. Check TOML syntax (quotes, brackets)
2. Validate with: `python3 -c "import tomllib; tomllib.load(open('~/.config/iterm2/layout.toml', 'rb'))"`

### Tabs Not Appearing

**Symptom**: iTerm2 opens but no custom tabs created

**Causes**:

1. No `[[tabs]]` entries in config
2. Config file in wrong location
3. Script not in AutoLaunch

**Solution**:

```bash
# 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
```

### Directory Does Not Exist Warning

**Symptom**: Tab skipped with warning in Script Console

**Solution**: Verify directory path exists or create it:

```bash
mkdir -p ~/path/to/missing/directory
```

## Error Handling Behavior

The script uses "print + early return" pattern:

1. **Missing config**: Logs instructions to Script Console, exits cleanly
2. **Invalid TOML**: Logs parse error with details, exits cleanly
3. **Missing directory**: Logs warning, skips tab, continues with others

**Viewing errors**: Scripts > Manage > Console in iTerm2

## Git Worktree Detection (Optional)

Enable dynamic tab creation for git worktrees:

```toml
[worktrees]
main_repo_root = "~/projects/my-project"
worktree_pattern = "my-project.worktree-*"
```

**How it works**:

1. Script globs for `~/projects/my-project.worktree-*` directories
2. Validates each against `git worktree list`
3. Generates acronym-based tab names (e.g., `AF-ssv` for `sharpe-statistical-validation`)
4. Inserts worktree tabs after main project tab

## References

- [iTerm2 Python API](https://iterm2.com/python-api/)
- [TOML Specification](https://toml.io/)
- [XDG Base Directory Spec](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
- [ADR: iTerm2 Layout Config](/docs/adr/2025-12-15-iterm2-layout-config.md)

## Post-Execution Reflection

After this skill completes, check before closing:

1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

© terrylica · MIT · terrylica/cc-skills

Similar skills

All skills for Notes, tasks and projects →

From the same set79

The whole set →
link-validator The link-validator skill detects absolute paths in markdown links that break when a skill is installed elsewhere. Run it before sharing a skill or after adding new links. CX Codex +1 127installs session-info session-info returns the active Claude Code session UUID and session chain cache details. Helpful for debugging and linking transcripts to sessions. CX Codex +1 127installs asciinema-analyzer The asciinema-analyzer skill searches asciinema text recordings for keywords, commands, errors, and patterns. Use it when reviewing terminal session history. CX Codex +1 127installs research-archival research-archival scrapes AI research conversations and web pages, saves them as markdown with YAML frontmatter, and opens cross-referenced GitHub issues once the writing account is confirmed. CX Codex +1 127installs asciinema-player asciinema-player — a skill for Claude Code and five other platforms that plays .cast terminal recordings inside a dedicated iTerm2 window. Files over 100 MB crash browser players; this skill streams them from disk. CX Codex +1 126installs impl-standards impl-standards — a set of coding rules: error propagation, constant extraction, progress logging for long operations, and dependency injection patterns. CX Codex +1 126installs bootstrap-monorepo bootstrap-monorepo scaffolds a polyglot monorepo using moon, proto, and Bun with a TypeScript control plane and strict boundary rules. CX Codex +1 126installs asciinema-converter asciinema-converter turns asciinema .cast recordings into clean .txt files for reading and search. It handles one file or a directory batch. CX Codex +1 126installs

Project sponsors

Companies that keep this analytics open