See: #8200

TLDR: A UUIDv4 was deemed too complicated, especially since 128 bit integers don't have a natural C type. I think keeping them as strings is even worse.

I personally think an opaque random 64 bit unsigned integer is the easiest, whereas Mitchell wanted something with some sort of structure to support some future theoretical distributed Ghostty system.

As an aside, testing the GTK apprt via docker is not sufficient. Most of the GUI code has no unit tests so just compiling and running unit tests is not sufficient testing.

Nomenclature-wise, Ghostty doesn't have "sessions", we have surfaces. If/when we introduce the notion of sessions it'll be something other than an individual active terminal. "Present surface" would be my preferred verb as it's already used in a few places already.

Thanks @jcollie for the guidance here — both your comment and your work on #8200 were really helpful in aligning on a solution. The u64 approach, the "present surface" naming, and the surface-level lookup pattern from your PR gave us a solid foundation to build on.

I've reworked the implementation based on your feedback. Updated branch: chris-spare/ghostty:feature/present-surface

Changes from my original focus-session branch:

• u64 surface IDs instead of UUIDs (per your recommendation and core: add a UUID to every core surface #8200)
• Renamed from focus-session/GHOSTTY_SESSION_ID to present-surface/GHOSTTY_SURFACE_ID
• GTK/Linux: ghostty +present-surface --id=0x... via D-Bus IPC
• macOS: ghostty://present-surface/0x... URL scheme (tested end-to-end)
• Replaced the raw pointer casting in desktop notification surface targeting with proper findSurfaceByID lookup

Re: testing — agreed that Docker compilation alone isn't sufficient for the GUI paths. The macOS URL scheme was tested end-to-end (multiple tabs, open ghostty://present-surface/0x... successfully focuses the correct tab with highlight). The GTK D-Bus path compiles and passes unit tests via Docker/Debian 13 but hasn't been runtime-tested — I don't have a Linux box and haven't figured out how to do virtual runtime testing on macOS. If runtime testing on GTK is a blocker, I'd appreciate any guidance on how best to approach that.

This discussion and the linked implementation were written with AI assistance (Claude Code), with human review and testing.

This would unlock another often overlooked feature: proper per-tab (surface) command history isolation and recovery.

In Iterm2 we can use the $ITERM_SESSION_ID variable which contains a UUID that is stable between restarts, tab reorderings etc so setting the HISTFILE env var to something that contains that unique identifier makes command history work properly across restarts.

Without this, after Ghostty is restarted, arrow-up inside a terminal will suddenly show commands from another terminal - very confusing.

another use case: in revdiff (a tui diff reviewer) we ship Claude Code and Codex plugins that spawn revdiff as an overlay in a split pane. on ghostty the launcher splits focused terminal of selected tab of front window, because nothing else is reachable from an external script. there's no env var, no controlling tty in the agent-spawned launcher, and single-process ancestry on macOS rules out pid walking. if the user switches tabs between triggering the action and the split landing, revdiff opens in the wrong tab.

the only workaround today is matching working directory against $PWD, which breaks when two tabs sit in the same repo. a stable per-surface id exposed as an inheritable env var (shape doesn't matter, u64 is fine) would let us do the same exact-match lookup we already use for iTerm2 (ITERM_SESSION_ID), kitty (KITTY_WINDOW_ID), and wezterm (WEZTERM_PANE).

On macOS: open "ghostty:///focus-session/$GHOSTTY_SESSION_ID" via a ghostty:// URL scheme, reusing ghosttySurface(id:) and ghosttyPresentTerminal

Aside: AppleScript and Apple's Shortcuts lets you focus a terminal now, xref #7634, #8961, and #11208. Apparently there are IDs for those, but I'm not on macOS and know nothing about them.

GTK still has nothing, and there's nothing cross-platform (though I'd argue that should wait for #2353), so this discussion is still relevant though.