13 KiB
psyTerm
A Wayland terminal and multiplexer built with GPUI 0.2.2 and alacritty_terminal 0.26.0. A separate server owns terminal emulation, shells, tabs, panes, and scrollback. GUI processes display its snapshots and send input commands. Closing a window detaches it; the shells keep running for the next local or remote connection.
Build and run
Use recent stable Rust (development uses 1.96) and Linux 5.3 or newer. GUI processes require a running Wayland desktop and a working Vulkan driver. The server and SSH bridge do not initialize GPUI, Wayland, or Vulkan, although the shared executable still needs its dynamically linked libraries installed.
Representative Fedora dependencies:
sudo dnf install gcc gcc-c++ make cmake pkgconf-pkg-config \
fontconfig-devel freetype-devel libxkbcommon-devel libxkbcommon-x11-devel \
libxcb-devel wayland-devel openssl-devel vulkan-loader mesa-vulkan-drivers \
dejavu-sans-mono-fonts
Representative Ubuntu dependencies:
sudo apt install build-essential cmake pkg-config \
libfontconfig1-dev libfreetype6-dev libxkbcommon-dev libxkbcommon-x11-dev \
libxcb1-dev libwayland-dev libssl-dev libvulkan1 mesa-vulkan-drivers \
fonts-dejavu-core
These are the relevant portions of Zed's Linux dependency script. GPUI 0.2.2 links the XKB X11 library even with only its Wayland backend enabled. Use your GPU vendor's Vulkan driver where appropriate.
cargo run --locked
cargo build --locked --release
./target/release/psyterm
The default command starts or reuses a local server, asks its zygote to fork a
GUI, and returns. Running it again opens another view of the same workspace.
The first attachment to an empty server creates a shell. Shells use the
server's $SHELL (falling back to /bin/sh), environment, and startup directory;
they receive TERM=xterm-256color and COLORTERM=truecolor.
The server retains its startup environment. Set shell or GUI environment
preferences before starting that server, or use --gui to launch a diagnostic
GUI directly from the current environment. After rebuilding, the server refreshes
its zygote for new GUI windows, preserving existing windows and shells. Changes
to server logic or the protocol still require restarting the server;
--shutdown also ends its shell sessions.
This build uses protocol version 2. An older server must be restarted before
attaching; the new psyterm --shutdown command can stop a version-1 server.
Finish any running work first, since shutdown ends its sessions, then launch
psyterm again to start the updated server.
Commands and connections
| Command | Behavior |
|---|---|
psyterm |
Open a local window through the server's zygote |
psyterm --remote user@host |
Open a local GUI connected to the remote server over SSH |
psyterm --gui |
Launch a GUI directly, bypassing the zygote |
psyterm --list |
Inspect tabs and panes in the running local server |
psyterm --shutdown |
Stop the local server and end its sessions |
psyterm --server |
Run the terminal server in the foreground |
psyterm --socket PATH |
Select a separate local server socket; combine with other options |
psyterm --bridge |
Proxy the binary protocol between stdin/stdout and a local server |
By default the socket is $XDG_RUNTIME_DIR/psyterm/server.sock, with a private
per-user temporary directory as fallback. A custom socket must have a real,
user-owned parent directory with mode 0700:
mkdir -m 700 "$XDG_RUNTIME_DIR/psyterm-dev"
cargo run --locked -- --socket "$XDG_RUNTIME_DIR/psyterm-dev/server.sock"
Sockets and log files are private to the current UID; peers are checked with
Linux credentials. Server and zygote logs are beside the socket as
server.sock.log and server.sock.zygote.log.
SSH uses BatchMode=yes: configure key/agent authentication and known-host trust
before connecting. The remote host needs a compatible psyterm executable in
its noninteractive SSH PATH. Override that executable with
PSYTERM_REMOTE_BIN; this direct-launch example uses the current environment:
PSYTERM_REMOTE_BIN=/home/me/bin/psyterm \
cargo run --locked -- --gui --remote me@workstation
SSH starts psyterm --bridge on the remote host, which starts or reuses that
host's server. stdout carries only framed protocol bytes. No TCP listener or
separate network authentication service is exposed. To end remote sessions,
run psyterm --shutdown on the remote host, for example through SSH.
Controls
| Input | Action |
|---|---|
| Ctrl/Cmd+Shift+P | Open the command palette |
| Click a tab | Switch the server's active tab |
+ or Ctrl+Shift+T |
Create a tab |
| Ctrl+Shift+D or Alt+\ | Add a pane beside the focused pane |
| Alt+Left / Right | Focus the adjacent pane, then adjacent tab at the edge |
| Alt+Shift+[ / ] | Switch to the previous / next tab |
| Alt+Shift+N or Alt+Shift+Right | Create a tab |
| Ctrl+Shift+Left / Right | Focus the previous / next pane |
| Ctrl+Shift+W | Close the focused pane and its shell |
| Ctrl+Shift+R | Edit the pane name |
| Enter / Esc while renaming | Save / cancel the edit |
| Save a blank name | Restore automatic pane naming |
Window × |
Detach this GUI; keep server sessions running |
| Drag / double-click / triple-click | Select text / word / line |
| Ctrl+Shift+C / V | Copy selection / paste with negotiated bracketed-paste mode |
| Mouse wheel / touchpad | Scroll terminal history |
| Shift+PageUp / PageDown | Scroll one page |
| Shift+Home / End | Jump to oldest history / live screen |
Navigation follows the shared bindings in ~/.config/zellij/config.kdl, with
Alt+\ from its default locked mode. Existing psyTerm shortcuts remain available;
Zellij's modal Ctrl bindings are left to terminal programs.
The command palette searches command names and keywords as you type. Arrow keys or Tab select a result; Enter runs it or opens a submenu. Escape returns to the parent menu, then closes the palette. “Switch to tab…” and “Focus pane…” offer live workspace lists. Commands without shortcuts, such as restoring automatic pane names, are available here too. Palette input never reaches the shell.
Typing returns to the live screen. Ctrl+C, Ctrl+D, Alt combinations, arrows, navigation keys, and function keys reach the terminal application. Alternate-screen applications receive shifted navigation; the wheel sends arrow keys when the application enables alternate scrolling.
Each pane has a name above its terminal content. The server chooses a manual
name first, then the running program's OSC title, then the shell's current
directory. Automatic directory names abbreviate the server’s home directory
with ~; pane headers and equal-width tabs truncate long names in the middle.
It checks shell directories every 500 ms, including while the shell is idle. Manual names survive program title changes and client disconnects;
returning to automatic naming uses the latest program title or directory.
When a shell exits, its pane closes automatically. An empty tab closes too,
and focus moves to an adjacent remaining pane or tab when needed. After the
last shell exits, the window stays open with + available to start another tab.
Clients share the server's active tab, focused pane, selection, and scrollback position. The most recent GUI resize sets each pane's grid size. These are shared views of one workspace, not independent per-client layouts. Tabs and panes survive GUI disconnects but are stored in daemon memory, not persisted across server shutdown or machine restart.
Appearance
The inset terminal surface and titlebar use the dark Sybil palette shared by
Huayra, Attractor, and Sybil. Tabs retain violet accents; pane headers use teal,
with a matching border around the active pane. The titlebar contains equal-width
tabs and connection/window controls. src/chrome.rs records the theme sources.
Tab changes and new panes slide with Neovide's 150 ms exponential window-motion curve. Outgoing content remains visible during the transition; only the incoming view accepts input and controls the terminal size.
Cursor motion adapts Neovide's four independently sprung corners: leading corners move first and trailing corners stretch behind. The blink follows buzzlocker: 500 ms solid after input, 500 ms cubic fade-out, then an immediate return to solid. An inactive window or pane shows a stationary hollow cursor. Neovide's MIT license and both sources are recorded in THIRD_PARTY_NOTICES.md.
Font preference is Hermit (including Hurmit Nerd Font variants), SF Mono, Noto Sans Mono, Iosevka, then another verified fixed-pitch family. Text uses 15 logical pixels and a 20-pixel line height. Rendering supports ANSI/256 colors, truecolor, bold/italic/dim, underline, reverse video, wide characters, and combining marks. Alacritty supplies terminal modes and 10,000 lines of scrollback by default.
Processes and source
| Component | Responsibility |
|---|---|
server.rs, session.rs |
Authoritative workspace, PTYs, child processes, parser, terminal grids, selection, scrolling, and resize |
protocol.rs, client.rs |
Versioned bounded messages, local socket / SSH transport, snapshot delivery |
launcher.rs |
Server startup, private paths, lifecycle locks, and the server-owned GUI zygote |
terminal.rs |
Snapshot-only GUI workspace and panes, command dispatch, focus, and animation scheduling |
commands.rs, bindings.rs, palette.rs |
Extensible command metadata, optional shortcuts, searchable nested menus |
pane_name.rs, label.rs |
Pane name editor, Unicode composition, and middle-truncated labels |
render.rs, cursor.rs |
Cached text and batched drawing; cursor motion and blink |
chrome.rs, colors.rs, fonts.rs |
Window chrome, terminal colors, font selection |
input.rs, main.rs |
Key/paste encoding and CLI/process-role dispatch |
The server starts the zygote on demand and manages its lifetime. The zygote
checks that it is single-threaded and forks GUI children before GPUI,
Wayland, Vulkan, font discovery, or executors initialize. Children inherit the
loaded executable mappings and avoid another exec; graphics and font setup
still happen in each child. This is a safe prefork foundation, not a guarantee
of the fastest possible launch time. Headless terminal/bridge use does not
start the zygote.
Add an action and registry entry in commands.rs, then handle it in the workspace
dispatcher to add a command. Shortcut hints are optional. The same recursive menu
model supports commands that lead to further choices.
Snapshot queues retain the newest frame for a slow client rather than an unbounded backlog. GUI rows keep their shaped text until the snapshot changes. ASCII runs, Unicode glyphs, backgrounds, and decorations are batched; cursor animation reuses prepared terminal rows. Blink holds use timed wakeups, and inactive cursors schedule no animation frames.
The project uses published crates, with no local Alacritty checkout required.
The small vendored xattr patch fixes GPUI's transitive
Linux ENOATTR compatibility issue. Cargo.lock records dependency versions.
Development
The development profile retains debug information and assertions with level-1 optimization, plus level-2 optimization for GPUI and shaping crates. Preserve these settings when evaluating responsiveness; full-grid shaping and scene construction are expensive in a completely unoptimized build.
cargo fmt --check
cargo check --locked
cargo test --locked
cargo clippy --locked --all-targets -- -D warnings
RUST_LOG=psyterm::timing=debug cargo run --locked -- --gui
prepare_us and paint_us measure CPU callback time in microseconds. They
exclude GPU execution, compositor scheduling, and presentation, so they are
not end-to-end input-latency measurements.
Tests cover protocol framing, socket ownership, binary bridge flushing, key/paste encoding, palettes, fonts, cursor curves, rendering assembly, PTY lifecycle, and server reattachment/layout behavior. Pane tests cover natural shell exit, empty-tab removal, focus preservation, idle directory changes, program/manual name precedence, title resets, and rename persistence. Editor tests cover Unicode selection and composition; protocol tests pin the previous version's shutdown handshake.
Live Hyprland checks verified GUI→zygote→server ancestry, a single-threaded zygote, no server GPU descriptors, two simultaneous GUIs, tabs/splits, and shell survival after detaching. An actual SSH connection to a separate headless server on localhost verified input and reattachment. Replacing a running executable refreshed its zygote while the original GUI and shell stayed alive. These are Linux checks; remote-network latency and macOS remain unverified.
Linux Wayland is the implemented platform; macOS is a future target. Current limits include side-by-side panes only, shared per-server viewport state, no disk-restored sessions, no configuration files, no application mouse reporting, no Kitty keyboard protocol, no OSC 52 clipboard access, and no clickable links.