Release v1.3.1-auto.1

Released: 2026-04-09

This is the inaugural release of Ghostty Automator — a fork of Ghostty v1.3.1 that adds an IPC automation protocol for programmatic terminal control. Where browser automation has Playwright and Puppeteer, Ghostty Automator brings the same capabilities to the terminal: discover surfaces, read rendered screen content with full styling, inject keyboard/mouse/text input, capture screenshots, and manage windows — all through Unix domain sockets with JSON framing.

🌟 Highlights

✨ Full IPC Automation Protocol (12 Actions)

A complete terminal automation protocol over AF_UNIX sockets with 4-byte length-prefixed JSON frames (max 16 MB). Clients can list_surfaces, get_screen, send_text, send_key, send_mouse, send_scroll, focus_surface, close_surface, resize_surface, screenshot_surface, new_window, and new_tab — all implemented for both GTK (Linux) and macOS platforms.

🤖 Standalone Distribution with Platform Coexistence

Rebranded as ghostty-automator with bundle ID com.hyperb1iss.ghostty-automator, separate IPC socket namespace (ghostty-automator-$UID/ghostty-automator.sock), and updated GTK app ID + D-Bus path. Installs and runs alongside upstream Ghostty without conflicts.

⚡ Span-Based Cell Encoding (~450x Compression)

The get_screen action supports a cells format that returns terminal content with full styling (foreground/background colors, bold, italic, underline, strikethrough, inverse). Span-based encoding groups consecutive characters with identical styles, reducing output from ~633KB to ~1.4KB for typical terminal content.

🔧 Complete CLI Tooling

All 12 automation actions are exposed as +<action> subcommands on the ghostty-automator binary — +list-surfaces, +get-screen, +send-text, +send-key, +send-mouse, +send-scroll, +focus-surface, +close-surface, +resize-surface, +screenshot-surface, +new-window, +new-tab. Each supports --format=json for scripted use.

📝 Claude Code Skill for AI Agents

Ships a skills/ghostty-terminal-automation/SKILL.md that teaches AI agents the full automation workflow: bootstrapping a Ghostty instance, discovering surfaces, reading screen state, injecting input, and verifying results via screenshots.

🤖 IPC Protocol

• Transport: AF_UNIX sockets with length-prefixed JSON frames across Linux and macOS
• Surface discovery: Iterates all tabs and split trees — non-focused tabs/splits are discoverable and actionable
• Path validation: Per-component validation requiring absolute paths; filenames like report..2024.png are handled correctly
• Unified 16 MB max message size across all layers (Zig client, Python client, macOS server, GTK server)
• Peer UID validation on connections for security; only same-user processes can connect
• W3C key codes for send_key — Enter, Escape, ArrowUp, KeyA–KeyZ, F1–F12, with modifier support (ctrl, shift, alt, super)

🖥️ Platform Implementations

• GTK (src/apprt/gtk/ipc.zig, ipc_server.zig): Threaded client I/O with glib.idleAdd for main-loop dispatch. 1s read timeout, 5s write timeout. Screenshot via GL readback with draw_mutex held during read to prevent renderer races
• macOS (macos/Sources/Features/IPC/IPCSocketServer.swift): Native Swift socket server integrated via libghostty. send_key validates key names and returns errors for invalid input
• Generic server (src/apprt/ipc/server.zig): Shared infrastructure with handler dispatch synced across both platforms for send_mouse, send_scroll, send_key
• C API (include/ghostty.h): send_mouse, send_scroll, send_key added to the C ABI enum and union for external consumers

🐛 Safety and Correctness Fixes

• Span buffer overflow: Flush span buffer before overflow when encoding wide terminal cells to JSON — prevents out-of-bounds write on 1024+ column terminals (Surface.zig)
• Duplicate surface listings: macOS list_surfaces tracks processed windows with ObjectIdentifier to prevent duplicates in tabbed window groups
• Socket robustness: 10-second read/write timeouts, explicit blocking mode, EAGAIN/EWOULDBLOCK retry handling
• Swift 6 Sendable: NSImage marked @unchecked @retroactive Sendable in DockTilePlugin.swift to satisfy region isolation under Swift 6

🔧 CI/CD and Distribution

• Multi-platform CI/CD pipeline (cicd.yml): Linux x86_64 + macOS ARM64 builds with artifact separation for Homebrew tap and GitHub Releases
• macOS 26 Tahoe support: CI switched to macOS 26 runners with Xcode 26.2 for full app bundle builds including NSGlassEffectView and ConcentricRectangle APIs
• Upstream workflow isolation: All upstream Ghostty workflows pinned to branches: [upstream-only] to prevent firing on the fork while preserving files for rebase compatibility
• Artifact packaging: Dual uploads per platform — binaries-* for Homebrew, release-* for GitHub Releases with platform-specific filenames (ghostty-automator-{platform}-{arch}.{ext})
• Install script: install.sh for curl-style installation
• Justfile: Task runner with recipes for build, run, test, format, install, and automator CLI shortcuts

📝 Documentation

• README.md: Full project documentation covering architecture, all 12 CLI actions with examples, protocol specification, build instructions, and project layout
• docs/rfcs/terminal-automation-protocol.md: Accepted RFC documenting the v1 protocol — action specifications, surface addressing, security model, span compression, platform-specific notes, and Phase 2/3 roadmap
• AGENTS.md: Agent development guide with build commands, test filtering, and directory structure

Upgrade Notes

• This is the first Ghostty Automator release. Install via GitHub Releases, the curl install script (install.sh), or build from source with zig build
• The binary is named ghostty-automator and uses a separate socket namespace — it does not conflict with upstream Ghostty installations
• Socket paths: Linux $XDG_RUNTIME_DIR/ghostty-automator/<instance>.sock, macOS $TMPDIR/ghostty-automator-$UID/<instance>.sock
• Requires Zig 0.15.2 to build. macOS app bundle builds require Xcode 26.2 (macOS 26 SDK)
• The Python MCP package (ghostty-mcp) has been removed in favor of the CLI-based +<action> approach. Use ghostty-automator +<action> commands directly