TTYbird is a Rust TUI tool that lists Claude Code and Codex sessions running across terminals and jumps back to the original window. After building discovery and focus-return, the next feature I wanted was a two-pane view: the session list on the left, and a preview of the selected terminal on the right.
For tmux sessions or terminals spawned directly by TTYbird, reading the output stream is straightforward. The harder problem is previewing an already-running Ghostty tab without requiring tmux or restarting the agent. After testing macOS Accessibility (AXUIElement) and auditing Ghostty 1.3.1 (build 15212), I implemented a selection-driven snapshot preview using AppleScript perform action "write_screen_file:copy,vt" addressed by terminal UUID and rendered via libghostty-vt.
The responsibility boundary between TTYbird and Ghostty for existing-tab preview
Comparing Approaches for Existing Ghostty Tabs
| Approach | Mechanism | Findings & Trade-offs |
|---|---|---|
| UUID-directed file export (Implemented) | AppleScript perform action + write_screen_file:copy,vt | Addresses selected tabs, hidden tabs, and split panes by exact terminal UUID. Uses a temporary file and the clipboard, so it is designed as a one-shot snapshot on selection or r refresh. |
| macOS Accessibility (AX) read | AXUIElement (AXValue / AXStringForRange) | Reads Unicode and scrollback quickly (2.38–6.85 ms). Lacks a stable terminal UUID attribute, and splitting a pane invalidates the AX element reference. |
Linking libghostty directly | Internal ghostty_surface_read_text | libghostty-vt parses VT sequences, but an external process cannot obtain an in-memory surface handle from a running Ghostty app process. |
| Upstream viewport getter (Future proposal) | AppleScript or IPC returning viewport bytes by UUID | Would allow side-effect-free viewport reads without touching the system clipboard. |
Implementing the UUID Export Path
Ghostty's scripting definition exposes a read-only terminal ID and a targeted perform action. Its AppleScript handler resolves terminal id "..." across live surfaces and dispatches the action to that exact terminal without changing window or tab focus.
[TTYbird]
1. Save current clipboard representations in memory (up to 4 MiB)
2. Run AppleScript: perform action "write_screen_file:copy,vt" on terminal id <UUID>
3. Ghostty writes screen.txt in a private temp directory and places its file path on the clipboard
4. TTYbird reads the path and immediately restores the original clipboard contents
5. Parse VT bytes with libghostty-vt, render in the right pane, and delete the temp fileWhen a mapped Ghostty terminal is selected in TTYbird (or when the user presses r to refresh), TTYbird triggers write_screen_file:copy,vt. Ghostty's export implementation writes the terminal screen (including scrollback) to screen.txt and puts the temporary file path on the clipboard. TTYbird validates ownership and file mode, feeds up to 1 MiB of VT bytes into libghostty-vt (rendered at 120 columns, latest 200 rows), deletes the temporary file and directory, and restores the clipboard.
Native Verification on Ghostty 1.3.1
We verified the Rust adapter against a live Ghostty 1.3.1 instance across seven checkpoints (ghostty-export-evidence.json):
| Checkpoint | Verification Target | Result |
|---|---|---|
| E01 | Export selected tab by UUID and render Japanese output via libghostty-vt | Passed |
| E02 | Append new output to a hidden (unselected) tab and capture by UUID without switching tabs | Passed |
| E03 / E04 | Capture the original pane and a newly split pane separately by their respective UUIDs | Passed |
| E05 | Request export for a closed terminal UUID | Rejected cleanly as terminal-not-found |
| E06 | Clean up temporary files, private directories, and synthetic fixture processes | 0 remaining files / processes |
| E07 | Save and restore multi-format clipboard data (plain text + custom binary format) | Byte-for-byte match on readback |
Because macOS does not offer an atomic compare-and-swap operation on the general pasteboard, TTYbird avoids background polling and captures once per selection or explicit r refresh.
What the macOS Accessibility (AX) Investigation Showed
Before implementing the UUID export route, I tested Ghostty's AX implementation (SurfaceView_AppKit.swift) using a Swift probe (evidence.json). Four findings stood out:
AXVisibleCharacterRangereturns full scrollback, not just the viewport: On a 14-row terminal with 160 lines of output history,accessibilityValue()andAXVisibleCharacterRangereturned all 160 lines. In addition, when output contained Japanese text, combining characters, and emoji,AXNumberOfCharactersreported2,482while the string occupied2,488UTF-16 code units. Passing2,482toAXStringForRangetruncated the last 6 UTF-16 units, whereas2,488returned the full text.- 500 ms cache and
AXValueChanged: Ghostty cachescachedScreenContentsfor 500 ms. A read ~256 ms after output completion returned cached text, while a read at ~608 ms returned the updated text. Registering forAXValueChangedsucceeded, but 0 value-change notifications fired during terminal output updates (whereasAXTitleChangedfired as expected). - Hidden tabs vs. pane splits: Only the active tab's
AXTextAreaappears when enumerating the window's AX tree. Keeping a reference to a previously selected tab allowed reading new output while that tab was in the background, but splitting the pane invalidated the reference (kAXErrorInvalidUIElement). - Latency on large scrollback: With 306,612 characters of scrollback, the AX attribute read took 2.38–6.85 ms and full marker scanning took 38.14–61.24 ms across three samples.
Next Steps
Using write_screen_file:copy,vt gives TTYbird a practical snapshot preview for existing Ghostty tabs today without requiring a custom Ghostty build. Looking ahead, adding a small read-only viewport property to Ghostty's AppleScript terminal object would eliminate clipboard and temporary-file handling altogether and enable low-overhead live previews.