iterm2-layout

iTerm2 レイアウト設定

適切に関心を分離して iTerm2 のワークスペースレイアウトを設定します。プライベートなパスは TOML 設定に、公開可能なコードは Python スクリプトに記述します。

自己進化型スキル：このスキルは使用を通じて改善されます。手順に誤りがある、パラメーターがずれている、または回避策が必要だった場合は、後回しにせず、すぐにこのファイルを修正してください。実際に再現可能な問題がある場合にのみ更新してください。

このスキルを使用する場面

次のような場合にこのスキルを使用します。

• iTerm2 のワークスペースレイアウトを設定する
• ワークスペースのタブを追加、削除、または変更する
• iTerm2 の AutoLaunch スクリプトを設定する
• git worktree タブの自動検出を設定する

設定の概要

ファイルの場所

ファイル	場所	用途
設定ファイル（プライベート）	~/.config/iterm2/layout.toml	ユーザーのワークスペースパス
スクリプト（公開）	~/scripts/iterm2/default-layout.py	レイアウトのロジック
テンプレート	~/scripts/iterm2/layout.example.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"

セットアップ手順

初回セットアップ

/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

タブの追加

~/.config/iterm2/layout.toml に [[tabs]] エントリを追加します。

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

Name フィールド：

• 省略した場合は、ディレクトリのベース名が使用されます
• カスタム名は略称に便利です（例：「research-repo」の代わりに「AF」）

タブの削除

[[tabs]] エントリを削除するか、コメントアウトします。

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

設定スキーマ

セクション	キー	型	デフォルト	説明
[layout]	left_pane_ratio	float	0.20	左ペインの幅（0.0～1.0）
[layout]	settle_time	float	0.3	cd 後の待機時間（秒）
[commands]	left	string	br...	左ペインのコマンド
[commands]	right	string	zsh	右ペインのコマンド
[worktrees]	alpha_forge_root	string	null	worktree のルート（任意）
[worktrees]	worktree_pattern	string	*.worktree-*	Glob パターン
[[tabs]]	dir	string	必須	ディレクトリパス
[[tabs]]	name	string	basename	タブの表示名

トラブルシューティング

エラー：「Layout configuration not found」

症状：Script Console に設定が見つからないというエラーが表示される

解決方法：

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

エラー：「Invalid TOML syntax」

症状：Script Console に TOML の解析エラーが表示される

解決方法：

1. TOML の構文（引用符、角括弧）を確認します
2. 次のコマンドで検証します：python3 -c "import tomllib; tomllib.load(open('~/.config/iterm2/layout.toml', 'rb'))"

タブが表示されない

症状：iTerm2 は起動するが、カスタムタブが作成されない

原因：

1. 設定に [[tabs]] エントリがない
2. 設定ファイルの場所が間違っている
3. スクリプトが AutoLaunch に登録されていない

解決方法：

# 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

ディレクトリが存在しないという警告

症状：Script Console に警告が表示され、タブがスキップされる

解決方法：ディレクトリパスが存在することを確認するか、作成します。

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

エラー処理の動作

スクリプトでは「print + 早期 return」パターンを使用します。

1. 設定が見つからない場合：Script Console に手順を記録し、正常に終了します
2. TOML が無効な場合：詳細とともに解析エラーを記録し、正常に終了します
3. ディレクトリが見つからない場合：警告を記録してそのタブをスキップし、残りの処理を続けます

エラーの確認方法：iTerm2 の Scripts > Manage > Console

Git Worktree の検出（任意）

git worktree 用のタブを動的に作成する機能を有効にします。

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

仕組み：

1. スクリプトが ~/projects/my-project.worktree-* ディレクトリを Glob で検索します
2. 各ディレクトリを git worktree list と照合して検証します
3. 頭字語ベースのタブ名を生成します（例：sharpe-statistical-validation に対して AF-ssv）
4. worktree のタブをメインプロジェクトのタブの後に挿入します

参考資料

• iTerm2 Python API
• TOML Specification
• XDG Base Directory Spec
• ADR: iTerm2 Layout Config

実行後の振り返り

このスキルの実行後、終了する前に次の点を確認してください。

1. コマンドは成功しましたか？ — 成功しなかった場合は、失敗の原因となった手順またはエラーテーブルを修正してください。
2. パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、使用例とパラメーターテーブルを更新して合わせてください。
3. 回避策が必要でしたか？ — 異なるフラグや追加の手順など、その場で工夫する必要があった場合は、次回の実行で同じ回避策が不要になるよう、この SKILL.md を更新してください。

問題が実際に発生し、再現可能な場合にのみ更新してください。憶測で更新しないでください。