ghoztty

Ghoztty CLI Reference

Ghoztty is a fork of Ghostty that adds CLI-driven window management over a Unix domain socket. All IPC commands are idempotent — named targets that already exist are focused instead of recreated.

Prerequisites

Before running any ghoztty commands, verify it's available:

command -v ghoztty

If not found, tell the user:

ghoztty not found. Install it from https://github.com/dzearing/ghoztty/releases and make sure it's in your PATH.

Do NOT proceed if ghoztty is unavailable.

Know where you are: $GHOZTTY_PANE_ID

Every pane bakes its own identity into its processes' environment. When you are running inside a Ghoztty pane, you already know which pane you are — do not call +list to figure it out.

Variable	What it is
$GHOZTTY_PANE_ID	This pane's stable id (a UUID). Accepted directly by every --target/--name/--pane with no prior registration or +list. Stable for the pane's whole life, across app relaunch and session restore.
$GHOZTTY_WINDOW_NAME	The name of the window this pane is in, when it has one.
$GHOZTTY_IPC_SOCKET	The IPC socket of the app instance that owns this pane. The CLI reads it automatically — you never pass it, but it is why commands reach this app (e.g. a debug build) rather than whichever build is on $PATH.

So "open a side pane here" is one command:

ghoztty +split --pane="$GHOZTTY_PANE_ID" --direction=right

Rules that follow from this:

• Target your own pane explicitly. A bare +split goes to the most recently focused window — if the user clicks another window between their request and your command, the split lands in the wrong place. --pane="$GHOZTTY_PANE_ID" is immune to focus changes.
• Do not pass --working-directory for a plain split. A new split inherits the parent pane's cwd. Passing your own cwd overrides it, and the two diverge as soon as the shell cds somewhere.
• Do not call +list first. It is a wasted round trip when you only need your own pane, and it auto-registers every pane it walks. Use +list when you genuinely need to inspect other windows/panes.
• Prefer the pane id over pid/tty matching: pids and ttys are per-machine and are meaningless for remote panes. (+list --tty=<tty> remains a fallback for a process that has no baked env, e.g. one started before its pane existed.)