terminal-control

ターミナル制御

termctrl を使って、実際に表示されているターミナルの状態を確認し、決定的に操作します。

最小限のワークフローから始める

これ以上操作する必要がない場合は、一時的なターミナルアプリケーションの画面が落ち着いた時点で、表示されている画面を読み取ります。

termctrl show -- my-terminal-app

操作や繰り返しの確認が必要な場合は、アプリケーションを起動したままにします。

termctrl start app -- my-terminal-app
termctrl wait app "Ready"
termctrl show app
termctrl send app text:help enter
termctrl wait app "Commands"
termctrl show app
termctrl stop app

ユーザーがプロセスの実行継続を明示的に希望していない限り、使用後は名前付きセッションを必ず停止してください。

現在のターミナルペインでアプリケーションを表示して人が操作できる状態に保ちながら、同じセッション制御をエージェントにも公開します。

termctrl run -- /usr/bin/nvim
termctrl run editor -- nvim

NAME を指定しない形式では、実行ファイルのベース名（nvim）が使用され、名前が重複すると失敗します。末尾に番号を付けた名前が自動で選ばれることはありません。複数のコピーを実行する場合は、名前を明示的に指定してください。

適切な確認方法を選ぶ

• 現在表示されている画面のテキストには show を使います。全画面 TUI の推論では、こちらを優先してください。
• 通常画面のツールやログのようなコマンドから保持された出力を読み取るには、logs を使います。
• 永続化された成果物が必要な場合に限り、save --format ... --out ... を使います。
• --record でタイムラインを明示的に記録した後に限り、video を使います。

ログを代替画面 TUI の表示状態として扱わないでください。

名前付きセッションの読み取りは、デフォルトではすぐに返されます。出力が静かになるまで意図的に待つ場合に限り、待機時間を追加します。wait のデフォルトは 5 秒です。別の制限時間を選ぶ場合に限り、--timeout を設定してください。

デモを素早く行う場合は、セッションを起動したままにし、ゆっくり入力する意図がない限り --pace-ms を省略して、既知の画面遷移を 1 回のシェル呼び出しにまとめます。

termctrl send app text:help enter && termctrl wait app "Commands" && termctrl show app

テキストが表示されるとすぐに待機が終了します。タイムアウトは最大待機時間であり、固定の待機時間ではありません。これらのコマンドの間にスリープを挿入しないでください。操作中はテキストを確認し、視覚的な確認や要求された証拠に限り PNG を保存し、アプリケーションを操作した後に動画をエクスポートします。MCP では、キーボード入力、準備完了の確認、画面の読み取りを 1 回のツール呼び出しにまとめられる waitFor 付きの interact を優先してください。

入力を正確に操作する

通常のテキストは text:<value> で送り、名前付きキーは個別の入力要素として指定します。

termctrl send app text:/connect enter
termctrl send app down enter
termctrl send app ctrl-c
printf '%s' 'multiline prompt' | termctrl send app --stdin

入力を送信した後は、スリープしたりインターフェースが更新されたと決めつけたりせず、wait を使ってください。

マウス操作に対応したアプリケーションでは、ゼロ始まりのセル座標を使い、型付きマウスコマンドを指定します。

termctrl mouse app move 12 4
termctrl mouse app click 12 4
termctrl mouse app down 12 4
termctrl mouse app move 20 4
termctrl mouse app up 20 4

ボタンが押されていない状態での move はホバーし、down/move/up はドラッグします。--button right または middle、--shift、--alt、--ctrl は任意です。アプリケーションでマウスレポートが有効になっている必要があります。ホバーには任意イベントのトラッキングが必要です。サイズ変更後のビューポート外の座標は失敗します。レポート機能が無効な場合に、生のエスケープシーケンスを注入して回避しないでください。コマンドから要求された場合は、古い名前付きセッションを再起動してください。

デモを録画する場合は、video --pointer-overlay を有効にすると、滑らかな移動、控えめな押下時の圧縮、フェードを伴ってマウス入力が表示されます。デフォルトは 60 fps で、実際の入力を遅らせません。フェードのみを維持するには --pointer-reduced-motion を使います。トリミング、速度変更、停止の編集は、同じソースクロック上で行われます。オーバーレイの証拠となるのは型付きマウスコマンドのみです。生のバイト列や転送された人間の入力は対象外です。show／save は通常のターミナル証拠として、動画オーバーレイとは別に維持されます。

OpenTUI アプリケーションを操作する

OpenCode などのアプリケーションには、OpenTUI のホストハンドシェイクを使います。

termctrl start app --host opentui --cols 112 --rows 34 -- opencode
termctrl wait app "/connect"
termctrl show app
termctrl show app --format semantic

アプリケーションにより広い表示領域が必要な場合は、resize を使います。意図的にアプリケーションを再起動した後、保存済みの起動設定を再利用するには restart app を使います。

証拠を意図的に保持する

要求された形式のみを保存します。

termctrl save app --format txt --format png --out artifacts/current

ユーザーがタイムラインや動画の保存を希望する場合にのみ、デモを記録します。セッションの実行中にマーカーを追加し、停止後に確認してから、明示的な編集プランを使ってエクスポートします。

termctrl start app --record artifacts/run.termctrl -- my-terminal-app
termctrl wait app "Ready"
termctrl mark app ready
termctrl send app text:demo enter
termctrl wait app "Done" --timeout 60000
termctrl mark app done
termctrl stop app
termctrl markers artifacts/run.termctrl
termctrl show --recording artifacts/run.termctrl --at-marker done
termctrl video artifacts/run.termctrl --edit artifacts/run-edit.json --footer --out artifacts/run.mp4

ターミナルのテキストを読みやすく保つ必要がある場合は、編集プランの speed 値を控えめに設定します。最後のフレームを見せ場にする場合は、hold_ms または --tail-ms を使います。仕上がりのよいデモで、クリップのキャプション、経過タイムコード、「TERMINAL CONTROL」のブランディングを下部のフッターに表示する場合は、--footer を指定します。通常の動画では省略します。

.termctrl の録画、ANSI トランスクリプト、画面アーティファクト、コマンド引数、ターミナル入力は、機密情報を含む可能性があるものとして扱います。必要がない限り保持せず、内容を不必要に公開しないでください。

問題からの復旧

• termctrl status app を実行して、状態と起動設定を確認します。
• termctrl list を実行して、実行中の名前付きセッションを検出します。検出対象を絞り込むには --state、--command、または --cwd を追加します。保持済みの終了済みまたは利用できないエントリが関係する場合にのみ、--all を使います。
• MCP エージェントは list_sessions に state、command、または cwd を渡し、get_session_status({ name }) を使って CLI 出力を解析せずに、完全な構造化ステータスを取得できます。
• セッションのソケットパスが長すぎる場合は、セッションを開始する前に TERMCTRL_RUNTIME_DIR を /tmp 配下の短いプライベートディレクトリに設定します。
• termctrl を利用できない場合は、cargo install terminal-control で Terminal Control をインストールするか、使用するインストール済みバイナリをユーザーに確認します。