К основному содержанию
скилл CX Codex

iterm2-layout — скилл для Claude Code: что делает и как установить

Скилл iterm2-layout настраивает рабочие вкладки и панели iTerm2 через TOML-конфиг. Помогает агенту прописать пути проектов и включить автопоиск git worktree.

MIT 126 установок ★ 3 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add terrylica/cc-skills --skill iterm2-layout -a claude-code
Открыть на GitHub

Что делает iterm2-layout

Скилл управляет структурой терминала iTerm2, разделяя логику запуска и приватные пути. Сами директории и списки вкладок хранятся в ~/.config/iterm2/layout.toml, а скрипт генерации интерфейса находится в ~/scripts/iterm2/default-layout.py.

Через конфиг задаются пропорции сплитов (left_pane_ratio), стартовые команды вроде br и zsh, а также задержка settle_time. Дополнительно поддерживается поиск связанных git worktree по маске с автоматическим созданием вкладок для каждой ветки.

Для работы скрипт должен быть привязан к механизму AutoLaunch в iTerm2. Если директория проекта не существует, скрипт выведет предупреждение в консоль и пропустит вкладку.

Какие задачи решает

  • Задать структуру вкладок и панелей iTerm2 через единый файл layout.toml
  • Настроить автоматическое создание вкладок для git worktrees
  • Добавить или скрыть рабочую директорию проекта в терминале
  • Проверить синтаксис TOML-файла конфигурации с помощью Python

Примеры запросов агенту

  • Добавь вкладку для проекта ~/projects/analytics в ~/.config/iterm2/layout.toml
  • Настрой автопоиск git worktree для репозитория ~/projects/app
  • Проверь синтаксис конфига iTerm2 и создай недостающие директории

Как установить iterm2-layout

1Через Skills CLI (Vercel)

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

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/iterm2-layout/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об iterm2-layout

Как установить iterm2-layout в Claude Code?

Выполните команду npx skills add terrylica/cc-skills --skill iterm2-layout -a claude-code.

Что делает iterm2-layout?

Скилл даёт инструкции агенту по редактированию конфигурации вкладок iTerm2 в формате TOML, настройке параметров сплитов и диагностике скриптов автозапуска.

Где хранятся файлы конфигурации?

Пользовательские пути сохраняются в ~/.config/iterm2/layout.toml, а скрипт генерации макета размещается по пути ~/scripts/iterm2/default-layout.py.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Заметки, задачи и проекты» →
iterm2 julianobarbosa Настраивает iTerm2 и tmux, управляет панелями и сессиями и разбирает неполадки. Помогает работать с терминалом на macOS. CX Codex +1 115установок cli-anything-iterm2 HKUDS Скилл cli-anything-iterm2 для Claude Code подключает агента к живым сессиям iTerm2 через Python API: отправляет команды, читает вывод и scrollback, создаёт и помечает панели. CX Codex +1 559установок git-worktree julianobarbosa Управляет параллельными рабочими деревьями git worktree с созданием окон tmux и вкладок iTerm2. Помогает работать над ветками без stash. CX Codex +1 111установок modify-settings dominikmartn Скилл modify-settings для Claude Code находит и меняет параметры терминала Warp по схеме JSON Schema. Помогает настроить темы, шрифты и режим ввода в конфигурационном файле TOML. CX Codex +1 ★ 720звёзд репо orca-cli stablyai Скилл orca-cli для Claude Code управляет рабочими деревьями Orca, терминалами и встроенным браузером. Агент подключает его для передачи задачи другому агенту или проверки страницы в Orca. CX Codex +1 363 100установок Unterm zhitongblog MCP-сервер Unterm для Claude Code и других агентов: открывает панели, гоняет команды и снимает скриншоты терминала. Несколько агентов работают в одном окне одновременно. CX Codex +1 ★ 24звёзд репо

Из того же набора79

Весь набор →
link-validator Скилл link-validator проверяет markdown-ссылки в навыках на предмет абсолютных путей, которые сломаются при установке в другое место. Нужен перед распространением навыка или после добавления новых ссылок. CX Codex +1 127установок session-info Скилл session-info определяет UUID текущей сессии Claude Code и находит файл реестра цепочки. Пригодится при отладке и сопоставлении стенограмм. CX Codex +1 127установок asciinema-analyzer Скилл asciinema-analyzer для Claude Code ищет ключевые слова, команды и ошибки в текстовых расшифровках asciinema. Разбирает историю терминальных сессий. CX Codex +1 127установок research-archival Скилл research-archival скрейпит ссылки на исследования из ChatGPT, Gemini и Claude, складывает их в markdown с YAML-фронтматтером и заводит связанные GitHub Issues после проверки аккаунта. CX Codex +1 127установок asciinema-player Скилл asciinema-player для Claude Code и пяти других платформ воспроизводит .cast записи терминала в iTerm2 через отдельное чистое окно. Файлы больше 100 МБ браузерный плеер не тянет — этот скилл открывает их потоком с диска. CX Codex +1 126установок impl-standards Скилл impl-standards для Claude Code задаёт правила обработки ошибок, работы с константами, логирования прогресса и DI. Запускается при упоминании этих тем. CX Codex +1 126установок bootstrap-monorepo Скилл bootstrap-monorepo для развёртывания полиглот-монорепозитория на стеке moon, proto и Bun с типизированным слоем управления на TypeScript. CX Codex +1 126установок asciinema-converter Скилл asciinema-converter преобразует записи asciinema .cast в чистые .txt для чтения и поиска. Подходит для одиночных и пакетных конвертаций. CX Codex +1 126установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой