gpty

gpty [OPTIONS] COMMAND

gpty is the command-line client for gPTY, a Godot-and-Rust multi-PTY workspace. The GUI tiles independent shell sessions (and code, file-tree, Inspector, and Reasoning panes) in a resizable grid. Terminal rendering uses `alacritty_terminal` (DEC STD 070, 16/256/true color, scrollback with regex search, wrapped selection). The same binary launches or talks to that GUI over a JSON-RPC Unix socket so scripts and AI agents can spawn panes, inject input, and read output without scraping a TUI.Pane commands connect to `$XDGRUNTIMEDIR/gpty.sock` (or GPTY_SOCKET / --socket). If nothing is listening and --no-daemon was not passed, the CLI tries to spawn a sibling gpty-editor or gpty-gui binary, or the path in GPTY_GUI. schema, version, and --skill do not need the GUI.A concept is a regex trigger on PTY output that captures a reply and routes it into another pane (code viewer or Inspector). Concepts are display-only: they never write into a shell. The Inspector and Reasoning panes observe agent lifecycle events; gpty does not orchestrate agent state.Linux, macOS, and Windows binaries are published on GitHub Releases. No Godot or Rust toolchain is required to run them. The project is licensed GPL-3.0-or-later.

--skill

Print the bundled agent skill (`SKILL.md`) and exit. No IPC, no GUI.

Machine-readable JSON output (global).

IPC socket path. Default is `$XDGRUNTIMEDIR/gpty.sock` on Linux when that directory is user-owned and mode `0700`; otherwise `/run/user/<uid>/gpty.sock`, then `/tmp/gpty-<uid>.sock`. Overridden by GPTY_SOCKET.

Connection timeout in milliseconds (default `5000`).

Do not auto-spawn the GUI if it is not running.

Verbose logging to stderr.

Open a pane. -t, --pane-type is `terminal` (default), `codeviewer`, `filetree`, `inspector`, or `reasoning` (`observer` is a deprecated alias for `inspector`). -c, --command runs a shell command in a terminal pane. -s, --split is `left`, `right`, `top`, or `bottom` (default `bottom`). --title sets the pane title. -f, --focus focuses the new pane (default true). --tags is a comma-separated list of broadcast tags.

List active panes with stable ids, labels, types, and positions.

Close a pane by id, label (for example `T1`), or `active`.

Focus a pane by id or label.

Send text to a terminal pane. A trailing newline is appended.

Print plain-text output (viewport plus scrollback). --lines is 1–2000 (default `200`).

Status for one pane (`pid`, `running`, `exitcode`, `idlems`). Omit the pane to list every pane.

Run a command in a new terminal pane through the configured shell.

Block until pane output matches a Rust regex (max 1024 characters). Server-side deadline is 100–60000 ms (default `10000`).

Inject text into every terminal pane that carries one of the given tags.

List concept triggers and whether each is enabled.

Enable or disable a concept by name.

Save, restore, or list named workspace layouts. Loading an untrusted profile over the control socket is refused (a CLI caller cannot answer the Workspace Trust dialog).

Print a JSON Schema of every command. `--format mcp` prints an MCP tool manifest. Works without a running GUI.

Run as an MCP server over stdio. Tools map to the same clap subcommands (`new-pane`, `inject`, `pane-read`, and so on).

Probe or stop the GUI. Most other subcommands already auto-spawn it unless --no-daemon is set. stop sends `shutdown` over IPC.

Print the CLI version and IPC protocol (currently `2.0`). No GUI required.

GPTY_SOCKET

Absolute path of the control socket. Relative values are ignored on Unix.

Optional shared secret for the control socket. The GUI and CLI must agree; a mismatch is treated as unauthorized.

Absolute path of the GUI binary used when auto-spawning. The path must be a user-owned regular file that is not group- or world-writable.

This is a graphical multiplexer, not a drop-in tmux/zellij replacement. There is no attach-from-an-existing-tty session model; the CLI drives a Godot GUI.Same-UID processes are trusted. GPTY_SECRET raises the bar for the socket but does not change that trust class. The socket is mode `0600` with a peer-UID check on Linux and macOS. When `$XDGRUNTIMEDIR` is missing, the fallback under `/tmp` can be pre-created by another user (denial of service, not traffic spoofing).Panes run as you, with no sandbox. Scrollback is stored in plaintext. Concept definitions cannot execute commands (that path was removed in 0.5.x). `layout load` over IPC refuses an untrusted profile; only the GUI Workspace Trust dialog can approve one.The current line is 0.5.x (0.5.3 as of 2026-09-10). Versions below 0.5 are unsupported. The project documents that much of the Godot UI and Rust GDExtension bridge was LLM-generated and may contain bugs.

gPTY was created by Neil Pathare. 0.1.0 (2026-07-21) shipped the tiling multi-PTY GUI, `gpty-core` engine, and a first CLI. The public API (JSON-RPC, clap CLI, MCP) and agent-oriented panes landed through the 0.5 series. The CLI crate is the gpty binary, versioned with the rest of the workspace.

tmux(1), zellij(1), screen(1), kitty(1), wezterm(1), alacritty(1)

Source code · Homepage · Documentation