ghostline

ghostline

ghostline is an embeddable terminal engine for Go. It owns real pseudo-terminals, keeps sessions running independently of attached clients, stores raw output in append-only spools, and renders complete terminal replays with libghostty-vt.

It provides terminal mechanics rather than a transport or UI. Applications can build a local multiplexer, remote shell service, development agent, browser terminal, or their own session protocol on top.

Capabilities

• Process-owned PTY sessions with input, resize, and exit reporting
• Ghostty-compatible VT state, scrollback, colors, alternate screens, and synchronized output
• Raw append-only output subscriptions with resumable byte offsets
• Atomic checkpoints pairing a full VT replay with its exact spool boundary
• Configurable VT scrollback budgets with a 2 MiB default
• Detached-mode terminal query responses for TUIs
• Rolling server upgrades that keep PTY children and emulator state alive, including a bounded spool-replay bridge for pre-0.6.0 sources
• Local Hub and Unix-socket Server/Client with one Session API

Requirements

• Go 1.25+
• Unix-like system (macOS, Linux, BSD)
• libghostty-vt; see libghostty-vt below

Quick start: local hub

hub, err := ghostline.New(ghostline.Options{
	OutputDir:   "/var/lib/my-app/terminals",
	DefaultSize: ghostline.Size{Columns: 120, Rows: 36},
})
if err != nil {
	return err
}
defer hub.Close()

session, err := hub.Start(ctx, ghostline.SessionOptions{
	Name:        "build-shell",
	Directory:   "/path/to/worktree",
	Command:     "bash",
	Environment: []string{"MY_APP=1"},
})
if err != nil {
	return err
}

watcher, err := session.WatchOutput(ghostline.WatchOptions{
	OnOutput: func(data []byte) {
		_, _ = os.Stdout.Write(data)
	},
})
if err != nil {
	return err
}
defer watcher.Close()

_ = session.Input(ctx, []byte("go test ./...\r"))
_ = session.Resize(ctx, ghostline.Size{Columns: 100, Rows: 30})

WatchOutput starts at a raw spool offset. Its callback receives a borrowed slice that is valid only until the callback returns; copy it if it must be retained. File notifications wake idle watchers when output arrives on Darwin and Linux; a low-frequency heartbeat covers filesystems that miss or coalesce notifications without continuously polling every Session.

VT scrollback and raw spool retention are separate. Configure the default VT scrollback for a Hub with Options.VTScrollbackMaxBytes, or override it for a single session with SessionOptions.VTScrollbackMaxBytes. See scrollback and output retention for the retention model, recommended values, and comparisons with other terminal runtimes.

Child processes inherit the embedding process's environment; SessionOptions.Environment overrides individual KEY=value entries. When the resulting environment has no non-empty TERM, ghostline sets one from Options.DefaultTerm, defaulting to xterm-256color, so detached daemons start shells without a terminal type warning.

Quick start: server and client

Run the standalone daemon:

go run ./cmd/ghostline serve --socket /tmp/ghostline.sock

Embed the server, or connect from another process:

client := ghostline.NewClient("/tmp/ghostline.sock")
if err := client.Check(ctx); err != nil {
	return err
}

session, err := client.Start(ctx, ghostline.SessionOptions{
	Name:      "remote-shell",
	Directory: "/srv/worktree",
	Command:   "bash",
})
if err != nil {
	return err
}

Client.Start returns a Session with the same methods as a local one, including Wait, Checkpoint, and Recover. Clients and the server must share the same filesystem because output watchers read the spool files directly.

Rolling server upgrades

The server can be upgraded without ending sessions. Both processes must speak the admin-socket protocol, and the new server must use the same output directory as the old one. A fresh server adopts every session from the old one over its management socket, then serves in place of it:

ghostline serve --socket /tmp/ghostline-new.sock --adopt-from /tmp/ghostline.sock.admin

Adoption is all-or-nothing:

• The old server pauses each session at a stable point, drains pending PTY output into the spool and emulator, and transfers the master fd over SCM_RIGHTS together with the encoded terminal snapshot.
• The new server prepares every session before committing any of them. If any session fails to prepare, the whole batch is aborted and the source server keeps serving unchanged. The new emulator restores each session's snapshot, including its grid, scrollback, cursor, and terminal modes.
• After the batch commits, the new server binds its public socket and the old server is asked to retire. Retirement confirmation is best-effort; once the batch commits, the new server keeps serving the adopted sessions even if the source endpoint closes without a response. Children never see a disconnect, and spool offsets stay valid because the spool is never rewound.

The embedding daemon coordinates the switch and retires the old process; see docs/rfc/0002-serve-rolling-upgrade.md.

Server bootstrap

Connect starts the server when the socket is missing:

client, err := ghostline.Connect(ctx, ghostline.ConnectOptions{
	Socket: "/tmp/ghostline.sock",
})
if err != nil {
	return err
}
defer client.Close()

The default spawn command is ghostline serve --socket <path>. Spawn can override it, with {socket} replaced by the socket path; Env and Log configure the spawned process. Ensure pre-warms the server without an operation. A spawn that exits before becoming ready is reported immediately, including its output. Concurrent Connect calls are safe: the first server to bind wins, and the other clients attach to it without owning it.

Recovery is lazy and restricted: read-only calls and Start may respawn and retry once after a dead socket. Input, Resize, Close, Remove, and spool maintenance are never retried automatically. Close stops only the server this client spawned; connecting to an existing server is a no-op.

Checkpoints

For a lossless reattach or window switch, pause the watcher and use an atomic checkpoint:

watcher.Pause()
checkpoint, err := session.Checkpoint(ctx)
if err == nil {
	err = watcher.SkipTo(checkpoint.Offset)
}
if err == nil {
	_, err = client.Write(checkpoint.Replay)
}
watcher.Resume()

Bytes below Checkpoint.Offset are represented by Checkpoint.Replay; bytes written afterwards remain available to the resumed watcher.

minimux example

examples/minimux is a small in-process terminal multiplexer built on the public Hub and Session APIs:

cd examples/minimux && go run .
cd examples/minimux && go run . -- htop

It demonstrates multiple live windows, background TUI query responses, terminal resizing, output subscriptions, and atomic VT replay on window switches.

libghostty-vt

The repository includes the Ghostty C headers and a prebuilt macOS arm64 library. Other platforms must build libghostty-vt from Ghostty source with Zig 0.16.0 or newer:

The bundled copy is built from Ghostty commit 5851d986 (1.3.2-dev) with Zig 0.16.0 and ReleaseFast optimization.

brew install zig@0.16
git clone https://github.com/ghostty-org/ghostty
cd ghostty
/opt/homebrew/opt/zig@0.16/bin/zig build \
  -Doptimize=ReleaseFast -Demit-lib-vt=true

Point the external linker and runtime loader at that build on platforms that do not use the bundled macOS arm64 library:

export GHOSTTY_VT_DIR="$HOME/Workspace/gh/ghostty/zig-out"
export CGO_LDFLAGS="-L$GHOSTTY_VT_DIR/lib"
export DYLD_LIBRARY_PATH="$GHOSTTY_VT_DIR/lib${DYLD_LIBRARY_PATH:+:$DYLD_LIBRARY_PATH}" # macOS
# export LD_LIBRARY_PATH="$GHOSTTY_VT_DIR/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"   # Linux

Builds with CGO_ENABLED=0 compile, but Hub.Check and Start return ErrUnavailable because VT emulation requires libghostty-vt.

Protocol and security

The server speaks JSON-lines over a Unix socket and creates the socket with mode 0600. The rolling-upgrade management socket (<socket>.admin) uses the same mode and is only ever connected to by a fresh server process, never by clients. The RPC enforces an idle deadline, a message size limit, and a concurrent connection cap. Both sockets are designed for same-machine, trusted callers; there is no authentication. Do not expose them to untrusted users.

Lifecycle

• Start rejects names that are already known; call Remove before reusing a name.
• Close terminates a session but keeps its record and spool for inspection.
• Remove deletes the in-memory record; spool files stay on disk.
• Hub.Close terminates every session.
• Session.Wait returns an ExitError with the exit code or signal. A child that exits after a rolling upgrade may report ExitError.Unknown, because its new owner cannot recover the old process's wait status. Context cancellation stops waiting but does not terminate the child.
• Status distinguishes a stopped session from a remote network failure; Alive is a best-effort convenience.
• Sessions implement MetadataProvider.Metadata, reporting the OS-level foreground process and working directory. It is opt-in: construct the Hub/Server with ProbeForeground: true (or pass --probe-foreground to ghostline serve). The probe resolves the PTY's foreground process group with TIOCGPGRP and reads the process from /proc on Linux or ps/lsof on macOS. Disabled by default; Metadata returns empty values without probing.
• Spool maintenance lives on Session: Recover, TruncateSpool, ArchiveSpool, and RemoveSpool.
• Use errors.Is with ErrUnavailable, ErrClosed, ErrSessionExists, ErrSessionNotFound, ErrSessionClosed, and ErrInvalidSessionName; error identity is preserved across the RPC boundary.

Layout

• hub.go - session hub and start options
• session.go - local and remote session API
• process.go - PTY child lifecycle
• migrate.go - rolling-upgrade admin protocol and session adoption
• spool.go - append-only output watcher
• query.go - detached-mode terminal query responder
• terminal.go - libghostty-vt CGo wrapper
• rpc.go, client.go, server.go - Unix-socket protocol
• cmd/ghostline - standalone server command
• examples/minimux - runnable terminal multiplexer example