LLM によるターミナル操作

v0.11 で導入

Web ブラウザの操作自動化において Playwright が果たしている役割と同様に、LLM が TUI（テキストユーザーインターフェース）を操作するには、画面の視覚状態を確認しながらキーを送り、その変化を観測するフィードバックループが必要です。しかし、通常の CLI 実行ではプロセスが画面描画の完了と同時に終了してしまうため、vim や fzf、対話的インストーラーのような状態を持つアプリケーションを操作できません。

console2svg session は、バックグラウンドのデーモンプロセスが擬似端末（PTY）の対話セッションを保持し、LLM が JSON 経由で段階的に操作を進めるための対話インターフェースを提供します。 LLM は画面のテキスト配置や SVG キャプチャを「目」として観測し、TUI のレイアウト調整や動作確認を自律的に繰り返すことができます。

エージェント向けの前提設定

LLM にターミナル操作手順を指示するには、あらかじめ用意されたエージェント向け指示書である SKILL.md をプロンプトまたはシステム指示へ読み込ませます。エージェントは指示書に従い、次に解説する JSON ベースのコマンド群を実行して作業を進めます。

すべての console2svg session サブコマンドは、結果を標準出力へ JSON 形式で返します。 LLM がテキストの曖昧な正規表現解析に頼ることなく、終了ステータスや画面状態を構造化データとして確実に取得できるようにするためです。失敗時の分岐には error.code を使ってください。error.message と標準エラー出力の診断文は人向けで、文面が変わる場合があります。

対話操作の基本フロー

LLM がセッションを操作する手順は、開始、寸法設定、画面確認、入力送信、停止の 5 段階で構成されます。

1. セッションの開始

操作対象のコマンドを指定してバックグラウンドセッションを起動します。

console2svg session start -- bash

実行に成功すると、セッションを一意に識別する sessionId を含む JSON が返されます。以降の操作では、この ID を引数として指定します。

{
  "sessionId": "s_a1b2c3d4e5f6",
  "state": "running",
  "command": "bash",
  "width": 80,
  "height": 24,
  "createdAt": "2025-01-15T10:00:00Z"
}

2. 画面寸法の調整

TUI アプリケーションの多くは、端末の幅や高さに応じてレイアウトを変化させます。目的に応じて画面サイズを変更する場合は session resize を実行します。

console2svg session resize s_a1b2c3d4e5f6 --width 120 --height 30

3. 画面状態の観測

送信したキーに対する反応を確認するため、画面上のテキストまたは SVG 画像を取得します。

# 現在の画面テキストをすぐ取得
console2svg session read s_a1b2c3d4e5f6

# 文字列の出現、または一度表示された文字列の消失を待機
console2svg session wait s_a1b2c3d4e5f6 --text "Ready"
console2svg session wait s_a1b2c3d4e5f6 --text "Working" --until absent --stable-for 2s

# 現在の画面状態を SVG 画像として保存
console2svg session capture s_a1b2c3d4e5f6 -o /tmp/current-screen.svg

# 出力先を指定しない一時的な目視確認（Observation。Scenario エクスポート対象外）
console2svg session inspect s_a1b2c3d4e5f6

session read は現在の画面上の文字列、0 始まりのカーソル座標と表示状態、代替画面の状態、スクロールバック行数、表示範囲をすぐ返します。--structured を加えると、セル単位のスタイル、ハイパーリンク、全角文字情報を含むバージョン付きデータも取得できます。条件待ちは session wait --text <literal> を使い、消失を待つ場合は対象文字列が一度画面に出た後に消えることを確認します。--stable-for で条件の安定時間、--timeout で上限のない任意の待機時間を指定できます。session capture は色やフォント属性を含む実際の描画結果を保存します。session inspect は同じ描画内容をユーザーごとの一時 SVG に書き出してパスを返します。目視確認だけなら inspect、成果物として残すなら capture -o を使います。マルチモーダル対応の LLM であれば、生成された SVG 画像を直接読み込んでレイアウト崩れや配色の違和感を検知できます。 session list は既定で起動処理中・実行中のセッションを表示します。session list --all で保持中の終了済み・利用不能セッションも見つけられ、分かる場合は expiresAt が表示されます。保持期間中は ID で読み取りやキャプチャができます。session stop で明示的に停止したセッションは削除され、ID からアクセスできなくなります。

4. キー入力の送信

画面状態を確認したら、次に行う操作のキーシーケンスを端末へ送信します。

# 通常の文字列を送信
console2svg session send s_a1b2c3d4e5f6 --text "git status"

# Enter や矢印キーなどの特殊キーを送信
console2svg session send s_a1b2c3d4e5f6 --keys Enter

# テキスト、貼り付け、キー入力を指定順に連続送信
console2svg session send s_a1b2c3d4e5f6 --text "i" --keys Enter --paste "hello" --keys Esc

--text、--paste、--keys、--raw-hex は複数回指定でき、指定した順序で送信されます。アプリケーションが有効にしている場合にブラケット付き貼り付けマーカーを付けるには --paste を使います。意味キーのカーソル・キーパッド入力はアプリケーションが選択した端末モードに従います。送信後は再び session read を呼び出し、期待する画面状態に遷移したかを検証します。

5. セッションの破棄

操作が完了したら、バックグラウンドに残ったプロセスを明示的に終了します。

# 特定のセッションを停止
console2svg session stop s_a1b2c3d4e5f6

# 起動中の全セッションを一括停止
console2svg session stop --all --yes

セッションを停止すると、バックグラウンドデーモンが PTY を閉じ、関連する子プロセス群と一時ソケットファイルをクリーンアップします。