cli-anything-iterm2
ステートフルな iTerm2 用 CLI ハーネス。WebSocket 経由で iTerm2 Python API を使用して、動作中の iTerm2 プロセスを制御します。
前提条件
- macOS + iTerm2 が動作していること:
brew install --cask iterm2 - Python API が有効になっていること: iTerm2 → 環境設定 → 一般 → マジック → Python API を有効化
- インストール:
pip install cli-anything-iterm2(またはソースからpip install -e .)
基本的な構文
cli-anything-iterm2 [--json] <グループ> <コマンド> [オプション] [引数]
機械可読な出力が必要な場合は必ず --json を使用してください（エージェント使用時に必須）。
コマンドグループ
| グループ | 目的 |
|---|---|
app | アプリの状態、ワークスペースのスナップショット、コンテキスト管理、アプリレベルの変数、モーダルダイアログ、ファイルパネル |
window | ウィンドウの作成、一覧表示、閉じる、リサイズ、全画面表示 |
tab | タブの作成、一覧表示、閉じる、アクティブ化、方向指定による分割ペインの移動 |
session | テキスト送信、生バイト注入、画面読み取り、完全スクロールバック、分割ペイン、プロンプト検出 |
profile | プロファイル一覧、プロファイル詳細、カラープリセットの一覧/適用 |
arrangement | ウィンドウレイアウトの保存と復元 |
tmux | 完全な tmux -CC 統合: ブートストラップ、接続、ウィンドウ、コマンド |
broadcast | ブロードキャストドメインを介したペイン間のキーストローク同期 |
menu | iTerm2 の任意のメニュー項目をプログラム的に呼び出し |
pref | グローバルな iTerm2 設定の読み書き、有効なキーの一覧表示、tmux 設定 |
既存ワークスペースへの導入
既存のペインがあるセッションに接続し、各ペインの画面内容全体を読み取らずに何が実行されているかを把握する必要がある場合は、app snapshot を使用します:
cli-anything-iterm2 --json app snapshot
すべてのウィンドウ、すべてのセッションについて、名前、カレントディレクトリ、フォアグラウンドプロセス、user.role ラベル、最後の表示出力行を返します。
命名規則 — ワークスペースをセットアップする際にペインにラベルを付けて、後で見つけやすくします:
cli-anything-iterm2 session set-var user.role "api-server"
cli-anything-iterm2 session set-var user.role "log-tail"
cli-anything-iterm2 session set-var user.role "editor"
app snapshot はこれらの役割をプロセスやパスと一緒に表示し、1回の呼び出しで全体像を把握できます。
典型的なエージェントワークフロー
# 1. 概要把握 — すべてのセッションのスナップショット: 名前、パス、プロセス、役割、最終出力行
cli-anything-iterm2 --json app snapshot
# 2. コンテキストの確立（後続のコマンドのためにウィンドウ/タブ/セッション ID を保存）
cli-anything-iterm2 app current
# 3. 操作 — コンテキストが設定されていれば --session-id は不要
cli-anything-iterm2 session send "git status"
cli-anything-iterm2 --json session scrollback --tail 200 --strip
# 4. マルチペインワークスペースの作成 — スナップショットで識別できるようにペインにラベルを付ける
cli-anything-iterm2 session split --vertical --use-as-context
cli-anything-iterm2 session send "python3 -m http.server 8000"
cli-anything-iterm2 session set-var user.role "http-server"
リファレンスファイル
タスクに必要なものだけを読んでください。各ファイルは狭い関心事に特化しています（約10～30行）:
| ファイル | こんな時に読む |
|---|---|
references/session-io.md | テキスト送信、バイト注入、画面/スクロールバックの読み取り、選択範囲の取得 |
references/session-control.md | ペイン分割、セッションのアクティブ化/閉じる、リサイズ、名前変更、セッション変数 |
references/session-shell-integration.md | wait-prompt、wait-command-end、get-prompt、信頼性の高い send→wait→read パターン |
references/layout-window-tab.md | ウィンドウとタブの作成/閉じる/リサイズ、分割ペインの移動 |
references/layout-arrangement.md | ウィンドウレイアウトの保存と復元 |
references/app-context.md | スナップショット（導入）、状態、コンテキスト管理、アプリ変数、モーダルダイアログ、ファイルパネル |
references/profile-pref.md | プロファイル一覧/取得/プリセット、設定の読み書き、tmux 設定ショートカット |
references/broadcast-menu.md | 複数ペインへのキーストロークブロードキャスト、メニュー項目の呼び出し |
references/tmux-commands.md | すべての tmux CLI コマンド（ブートストラップ、送信、タブ、create-window、set-visible） |
references/tmux-guide.md | 完全な tmux -CC ワークフロー、ペイン→セッション ID マッピング |
references/json-session.md | session、window、tab、screen、scrollback、inject の --json スキーマ |
references/json-tmux-app.md | tmux、アプリダイアログ、設定、エラーの --json スキーマ |
REPL モード
引数なしで実行すると、対話型 REPL が起動し、コマンド間でコンテキストを維持します:
cli-anything-iterm2