Feature Request: Bring window-save-state to Linux/GTK

[ImBIOS]

Summary

The window-save-state config option currently only works on macOS, relying on Apple's NSWindowRestoration framework. I'd like to propose implementing equivalent functionality for the GTK (Linux/BSD) runtime so that Ghostty can restore windows, tabs, splits, and working directories across restarts on Linux.

Motivation

Session persistence is one of the most requested quality-of-life features. The macOS implementation is heavily used and well-loved. Linux users currently lose all context (window layout, split configurations, working directories) on every restart.

Related existing issues:

• Include scrollback history in state restoration #1847 (scrollback history in state restoration)
• Feature Request: Session Management with Better Default Undo/Restore UX #10584 (session management UX)
• Closed PR gtk: add GSettings support for window state persistence #9451 (GSettings-based window size persistence — had useful discussion around storage format and schema versioning)

Proposed Approach

Storage

A JSON file in $XDG_STATE_HOME/ghostty/window-state.json (falling back to ~/.local/state/ghostty/). This avoids GNOME-specific dependencies (GSettings/dconf) and works across all desktop environments and windowing protocols.

Phased Scope

Phase 1 — Minimal viable state:

• Window count, size, and maximized/fullscreen state
• Per-surface: working directory (from shell integration) and running command
• Per-window: tab count and ordering

Phase 2 — Full split tree:

• Serialize the binary split tree from class/split_tree.zig (orientation, ratios, surface references)
• Restore split layouts on startup

Phase 3 — Scrolling history (ties into #1847):

• Persist scrollback buffer content alongside window state

Save/Restore Triggers

• Save on Application.quit() and quit_timer expiration
• Optionally periodic saves (e.g. every 60s) for crash recovery
• Restore in Application.startup() after GTK initialization

Wayland vs X11

• X11: Restore window position and size (possible via the existing winproto/x11.zig abstraction)
• Wayland: Compositor controls positioning, so only restore size/tabs/splits — skip position restoration gracefully

Config Behavior

Reuse the existing window-save-state config with the same semantics:

• never — don't save or restore
• always — always save on exit
• default — system-dependent behavior

Why Not GSettings?

PR #9451 explored GSettings, but it introduces GNOME-specific coupling and schema compilation complexity. A plain JSON file in XDG_STATE_HOME is portable across KDE, Sway, Hyprland, i3, and any other environment.

Implementation Areas

All work would be in src/apprt/gtk/:

• New: window_state.zig — serialization/deserialization
• Modified: class/application.zig — save/restore hooks in startup/quit
• Modified: class/window.zig — expose state for serialization
• Modified: class/split_tree.zig — walkable tree serialization
• Modified: class/surface.zig — expose working directory

Questions for Maintainers

1. Is JSON acceptable as the storage format, or is there a preference for a custom binary format?
2. Should this be gated behind the existing window-save-state config or a separate Linux-specific config option?
3. Is phased implementation (starting with minimal scope) acceptable, or should we wait for a complete solution?
4. Any concerns about file I/O on the main thread during quit — should saves be async?

[jcollie]

I think that the core GTK developers have a consensus that session save/restore on Linux/GTK should wait until GTK's native session management API is released, which is supposed to happen with GTK 4.24. The only reason that macOS got session management support is that macOS already had native platform support for session management. We do not want to be writing our own session management system.

[fhackenberger]

You can use my implementation until then: #12962