複数のターミナルに散らばったClaude CodeやCodexのセッションを一覧し、元の端末へすぐ戻るためのRust製TUIツール「TTYbird」を開発しています。一覧から元のウィンドウへフォーカスを戻す機能に続いて欲しくなったのが、左側にエージェント一覧、右側に選択中のターミナル画面を表示するプレビュー機能でした。
tmux を使っているセッションや、TTYbird自身がPTYを起動したセッションであれば、出力ストリームを直接受け取って描画できます。難しかったのは、すでに通常のGhosttyタブで動いている作業を、tmuxへ移行したり再起動したりせずそのままプレビューしたいというケースです。Ghostty 1.3.1(build 15212)のソースコード調査と実機検証を行い、AppleScriptの端末UUID指定によるVTファイル書き出し(write_screen_file:copy,vt)と libghostty-vt を組み合わせることで、選択時のスナップショット表示を実装しました。
TTYbirdとGhosttyの既存タブ取得経路の整理
この記事では、最初に検証したmacOS Accessibility(AX)経由の読み取り特性と、最終的にTTYbirdへ実装したUUID指定のVTファイル書き出し経路、そして実機での計測結果をまとめます。
既存Ghosttyタブを取得するアプローチの比較
TTYbirdから既存のGhosttyタブの内容を取得する方法を整理すると、次のようになります。
| 取得方式 | 仕組み | 検証結果と特徴 |
|---|---|---|
| UUID指定ファイル書き出し(今回実装) | AppleScript perform action + write_screen_file:copy,vt | 選択中・非選択タブ・分割ペインすべてをUUIDで一意に指定して取得可能。一時ファイルとクリップボードを経由するため、選択時・更新キー(r)押下時のスナップショットとして実装。 |
| macOS Accessibility(AX)読み取り | AXUIElement の AXValue / AXStringForRange | テキストとスクロールバック履歴を高速(約2.4〜6.9ms)に取得可能。ただし端末UUIDとの対応付けがなく、ペイン分割時に要素参照が失効する。 |
| libghosttyの直接リンク | ghostty_surface_read_text 等の内部API | libghostty-vt はエスケープシーケンス解釈用ライブラリであり、別プロセスで動作中のGhosttyアプリ内の surface ハンドルには外部から接続できない。 |
| Ghostty側のviewport取得API(将来の拡張案) | AppleScriptまたはIPCでUUID指定のviewportを返す | クリップボードを経由せずに可視領域(viewport)のみを副作用なく取得できる最小の拡張案。 |
なぜ libghostty をリンクするだけでは接続できないのか
Ghosttyには端末のエスケープシーケンスを解釈して画面状態を構築する libghostty-vt があり、Ghostty本体の内部には ghostty_surface_read_text という関数も存在します。しかし、この関数を呼ぶにはGhosttyプロセス内部の surface ポインタが必要です。include/ghostty.h でもこれらは内部API(libghostty-internal)として区別されており、別プロセスであるTTYbirdにライブラリをリンクしただけでは、起動中のGhosttyタブのメモリ空間を読むことはできません。
また、Ghostty 1.3.1で追加された AppleScript API はウィンドウ・タブ・端末のUUID取得やフォーカス移動を公開しているため、「一覧から元の端末へ戻る」用途にはそのまま使えますが、画面のテキスト内容を直接返すプロパティ(getter)はまだ用意されていませんでした。
そこで、外部プロセスから既存のGhosttyタブを読む方法として、以下の2つの経路を実機で検証しました。
- AppleScriptの
perform actionからwrite_screen_file:copy,vtを呼び出す経路 - macOS Accessibility(AX)の
AXTextAreaからテキストを読み取る経路
実装した方式:UUID指定のVTファイル書き出しと libghostty-vt 描画
Ghostty 1.3.1のAppleScript辞書(Ghostty.sdef)には、特定の terminal id(UUID)に対してアクションを実行する perform action コマンドがあります。これとキーバインド用アクションの write_screen_file:copy,vt を組み合わせると、フォーカスを奪わずに指定UUIDの端末内容をVTエスケープシーケンス付きで一時ファイルへ書き出すことができます。
[TTYbird]
1. クリップボードの現在値をメモリへ退避(最大4MiB)
2. AppleScriptで対象UUIDへ perform action "write_screen_file:copy,vt" を実行
3. Ghosttyが一時ディレクトリに screen.txt を生成し、そのファイルパスをクリップボードへ格納
4. TTYbirdがパスを読み取り、即座にクリップボードを元の内容へ復元
5. screen.txt のVTバイト列を libghostty-vt でパースして右ペインに描画し、一時ファイルを削除Surface.zigの書き出し実装 を確認すると、copy 指定時にクリップボードへ入る値は画面のテキスト本文ではなく、ランダムな専用一時ディレクトリ内に作られた screen.txt のファイルパスです。形式には plain、vt、html を指定できるため、vt を選べば色や装飾を含んだバイト列をそのまま libghostty-vt に渡して再描画できます。
TTYbirdでの操作設計
この方式は一時ファイルの生成とクリップボードの書き換えを伴うため、バックグラウンドで毎秒ポーリングする方式には向いていません。そこで、TTYbirdではユーザーが一覧で端末を選択したとき、または明示的に更新したときだけ1回取得するスナップショット方式として設計しました。
- 紐付け済みのローカルGhostty端末を一覧で選択すると、そのUUIDに対して1回だけスナップショットを取得し、右ペインに表示します(120列・末尾最大200行)。
- 同じ端末を選択している間は自動ポーリングを行わず、
rキーを押したときに再取得します。 pキーでプレビュー表示の開閉を切り替え、Enterキーで元のGhostty端末へフォーカスを戻します。
クリップボードの退避・復元については、変更カウント(change count)と書き出されたファイルパスの所有者・通常ファイル判定を確認したうえで復元し、読み取り完了後に一時ファイルと一時ディレクトリを削除しています。
実機検証の結果(Ghostty 1.3.1)
実際のGhostty 1.3.1アプリとTTYbirdのRustアダプタを接続し、以下の7項目(E01〜E07)を検証しました(検証ログJSON)。
| 項目 | 検証内容 | 結果 |
|---|---|---|
| E01 | 選択中の通常タブをUUIDで指定して取得し、libghostty-vt で日本語出力を描画 | 成功 |
| E02 | 背面に隠れている非選択タブへ新しい出力を追加し、タブを切り替えずに同じUUIDで取得 | 成功 |
| E03 / E04 | ペイン分割を行う前からある端末と、分割で新しく作られたペインを別々のUUIDで取得 | 双方のマーカーを個別に取得成功 |
| E05 | すでに閉じた端末のUUIDを指定したときのエラーハンドリング | terminal-not-found として安全に拒否 |
| E06 | 取得後の一時ファイル・専用ディレクトリ・検証用プロセスの後片付け | 残存ファイル0・残存プロセス0 |
| E07 | プレーンテキスト+カスタムバイナリ形式を含むクリップボードの退避と復元 | 復元後の再読み取りでバイト列が完全一致 |
macOS Accessibility(AX)経路の検証で分かったこと
UUID書き出しを実装する前に、Ghosttyの SurfaceView_AppKit.swift が公開しているmacOS Accessibility(AXTextArea)経由の読み取りもSwift製プローブで詳しく検証しました(AX検証ログJSON)。AX経由でターミナルを読む際に注意すべき実装上の挙動を4点記録しておきます。
1. AXVisibleCharacterRange は可視領域ではなくスクロールバック全体を指す
初期状態で14行表示のターミナルに対して160行の履歴を出力したところ、AXValue および AXVisibleCharacterRange から返ってきた文字列には160行すべての履歴が含まれていました。Ghosttyの point.zig では画面上の可視領域(viewport)と保持履歴全体(screen)が明確に区別されており、AXの cachedScreenContents は後者を返す実装になっています。
また、日本語・結合文字・絵文字を含む出力で検証したところ、AXNumberOfCharacters が返す文字数は 2,482 だったのに対し、全文のUTF-16コード単位長は 2,488 でした。AXStringForRange に 2,482 をそのまま渡すと末尾の6 UTF-16単位が欠落するため、AXの範囲取得を扱う際はUTF-16単位での指定が必要です。
2. 500msキャッシュと AXValueChanged 通知の挙動
AXValueChanged 通知のObserver登録自体は成功しましたが、ターミナル出力を更新した区間での通知発火は 0件 でした(同じウィンドウでタイトルを変更した際の AXTitleChanged は2件正常に受信できています)。
また、出力完了から約256ms後の読み取りでは更新前の内容が返り、約608ms後の読み取りで新しい内容が返りました。これは SurfaceView_AppKit.swift の500msキャッシュ実装 と一致しています。
3. 非選択タブの保持と、ペイン分割による参照失効
同名タブを2つ開いた状態では、アクティブなAXツリーには現在選択されているタブの AXTextArea 1つだけが現れます。ただし、一度取得した AXUIElement の参照を保持していれば、そのタブが非選択(背面)になったあとに追加された出力もそのまま読み取ることができました。
一方で、そのタブ内でペイン分割を行うと、保持していた参照は kAXErrorInvalidUIElement となって失効しました。AX要素にはAppleScriptの端末UUIDに対応する識別子(AXIdentifier)が付与されていないため、同名タブや分割ペインが複数ある環境でAX要素だけを頼りに元の端末へ再接続すると、別のペインを取り違えるリスクがあります。
4. 大量履歴(約30万文字)取得時のレイテンシ
出力履歴を増やして 306,612文字 にした状態での計測では、AX属性取得API呼び出し自体は 2.38〜6.85ms、クライアント側での文字列走査を含めた全体処理は 38.14〜61.24ms(3サンプル)でした。単発の取得としては十分高速ですが、プレビューしていない全タブの全文を常時ポーリングするとクライアント側の文字列処理コストが積み重なるため、選択中の対象だけを取得する設計が適しています。
今後の展望:副作用のないviewport取得に向けて
今回の実装により、TTYbirdで既存のGhosttyタブを選択した際に、tmuxなしでもその場ですぐに端末出力を確認できるようになりました。
現状の write_screen_file:copy,vt を使う方式は、Ghostty本体にパッチを当てずにすぐ使える実用的な解法ですが、クリップボードと一時ファイルを経由するため「選択時・r キー押下時のスナップショット」に留めています。もし将来Ghostty側のAppleScript辞書またはIPCに以下のような小さな拡張が入れば、クリップボードに触れずに完全なライブプレビューが実現できます。
- AppleScriptの
terminalオブジェクトから、クリップボードを介さずに現在のviewport(可視範囲)のテキストまたはVTバイト列を直接返すプロパティ - 必要に応じたスナップショットのrevision番号または変更通知
まずは現在のスナップショット方式で日々のマルチエージェント作業を快適にしつつ、よりクリーンな取得経路についても引き続き検証していきます。