psyTerm

A terminal and multiplexer for macOS and Linux (Wayland), 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. Run psyterm --attach to return to the running shells, or psyterm to start a fresh session.

Build and run

Use recent stable Rust and build with --locked to use the dependency versions in Cargo.lock.

macOS

Install Xcode or its Command Line Tools (xcode-select --install). GPUI embeds its Metal shader source and compiles it when the GUI opens. To launch from a checkout, run cargo run --locked.

Install cargo-bundle once to build the Finder-launchable app. This is the version used by Zed.

cargo install --locked --git https://github.com/zed-industries/cargo-bundle \
  --rev 2be2669972dff3ddd4daf89a2cb29d2d06cad7c7 cargo-bundle

Build the release executable, package it, and sign the bundle locally.

cargo build --locked --release
CARGO_BUNDLE_SKIP_BUILD=true cargo bundle --release --format osx --select-workspace-root
codesign --force --sign - target/release/bundle/osx/psyTerm.app
open target/release/bundle/osx/psyTerm.app

You can copy psyTerm.app to Applications. All macOS windows share one Dock icon. Closing a window detaches its session. Cmd+Q detaches every window and keeps their shells, tabs, and scrollback in the daemon. Reopening the app from Finder, the Dock, or open resumes the most recently detached local session, including its SSH tabs. If all live sessions are attached, the app joins the most recently used one. If none exist, it creates a session.

Press Cmd+N or run psyterm from a shell to start an independent session in another window of the running app. The bundle’s Contents/MacOS/psyterm executable accepts the same CLI commands.

Linux

Use 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. Each invocation starts an independent session unless you pass --attach.

All Wayland windows use the app ID dev.buzzert.psyterm. Install the matching desktop entry and icon with the release binary so the desktop can group windows under the psyTerm launcher.

sudo install -Dm755 target/release/psyterm /usr/local/bin/psyterm
sudo install -Dm644 assets/dev.buzzert.psyterm.desktop \
  /usr/local/share/applications/dev.buzzert.psyterm.desktop
sudo install -Dm644 assets/psyTerm.svg \
  /usr/local/share/icons/hicolor/scalable/apps/dev.buzzert.psyterm.svg

Shells and sessions

Each new session starts with one tab and one shell. A pane opened above or below another pane starts in that shell’s current working directory. New tabs start in the server’s launch directory.

The New Window shortcut starts a fresh session in the focused pane’s directory on the same host. A remote window reuses the focused SSH connection’s executable and agent settings. For a nested SSH tab, the new window connects directly from your computer, so the nested host must be reachable using your local SSH configuration. Closing a window leaves its session available for reattachment.

Choose Switch to session… in the command palette to see your local sessions and the sessions on each directly connected SSH host, including detached sessions. For example, with one tab connected to vigilant, search for vigilant to see every live session on that host’s psyTerm daemon. Select one and press Enter. From a local workspace, another session on that host opens in an adjacent SSH tab. From a standalone SSH window, it opens in a window. An already open session can be focused directly.

The picker uses the existing SSH connection for discovery and refreshes while open. Tabs reached through a nested SSH connection are grouped under the session that hosts them. Remote discovery needs the updated local daemon and works with existing v6 SSH hosts.

From the CLI, run psyterm --list and pass the session ID to psyterm --attach ID. With no ID, --attach prefers the most recently used detached session and otherwise selects the most recently used attached session.

Shells inherit the server's environment and receive TERM=xterm-256color and COLORTERM=truecolor. The server uses $SHELL when set. On macOS it starts a login shell and falls back to the shell in your account settings. On Linux the fallback is /bin/sh.

The server retains its startup environment. Set shell preferences before starting the server. On Linux, use --gui to launch a diagnostic GUI directly from the current environment. After rebuilding on Linux, 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 6. Both ends of an SSH connection need this protocol. An older server must be restarted before attaching. psyterm --shutdown can stop servers using versions 1–5. 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 new local session in a new window
psyterm --attach [ID] Open a window on an existing session
psyterm --remote user@host Start a fresh SSH session in an adjacent tab when run from a local psyTerm pane, or a new window when run elsewhere
psyterm --remote --attach Reopen the last remote session you detached
psyterm --remote user@host --attach [ID] Reattach to an existing session on the SSH host
psyterm --gui Open a window in the shared macOS app or run a Linux GUI in the current process
psyterm --list Show local sessions, attached window counts, tabs, and panes
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.

socket_dir=$(mktemp -d /tmp/psyterm.XXXXXXXX)
cargo run --locked -- --socket "$socket_dir/server.sock"

Sockets and log files are private to the current UID. psyTerm checks the peer's UID using getpeereid on macOS and SO_PEERCRED on Linux. The server logs to server.sock.log beside the socket. The Linux zygote logs to server.sock.zygote.log.

From a local psyTerm shell, run psyterm --remote me@workstation to open a tab immediately to the right of the invoking tab. The command returns to the local shell while SSH connects. Run it again for an independent remote session, or add --attach ID to open an existing one. Use ssh me@workstation psyterm --list to find remote session IDs. Closing the window and reattaching to the local session restores its mixed tab bar. The + button creates a local tab in this workspace. Splitting a remote pane creates another shell on its SSH host.

To detach, hover over a remote tab and click ×, or focus it and choose Detach remote session in the command palette. If that SSH session has several tabs, they detach together. Its shells, running jobs, and scrollback stay on the remote host. Close pane still ends the shell in that pane.

Run psyterm --remote --attach from a local pane to bring back that workspace’s last detached remote session in the tab bar. From outside psyTerm, the same command reopens the most recently detached remote session in a window. The local daemon remembers these targets until it exits. If you detach a nested SSH session, run the command on the host that opened it. You can also select a session explicitly with psyterm --remote user@host --attach ID.

The local daemon must be running this build to close tabs, remember detached sessions, and pass SSH settings to new windows. Existing protocol-v6 sessions on the SSH host can stay running.

SSH uses BatchMode=yes. Configure key or agent authentication and trust the host key before connecting. The remote host needs a compatible psyterm executable on its noninteractive SSH PATH. To use a different path, set PSYTERM_REMOTE_BIN in the invoking shell.

PSYTERM_REMOTE_BIN=/home/me/bin/psyterm psyterm --remote me@workstation

SSH starts psyterm --bridge on the remote host, which starts or reuses that host's server. SSH carries input and terminal updates over its standard streams. To end remote sessions, run psyterm --shutdown on the remote host, for example through SSH.

Controls

Action macOS Linux
Open a new window and session Cmd+N Ctrl+Shift+N
Increase terminal text size Cmd+Plus or Cmd+= Ctrl+Plus or Ctrl+=
Decrease terminal text size Cmd+Minus Ctrl+Minus
Open or dismiss the command palette Cmd+Shift+P Ctrl+Shift+P
Create a tab Cmd+T or Option+Shift+Left / Right Ctrl+Shift+T
Add a pane to the right Cmd+D Ctrl+Shift+D or Alt+\
Insert a stacked pane above / below Option+Shift+Up / Cmd+Shift+D Alt+Shift+Up / Down
Focus the adjacent pane or tab Option+Left / Right or Cmd+Option+Left / Right Alt+Left / Right
Switch tabs Cmd+Shift+[ / ] Alt+Shift+[ / ]
Focus the previous / next stacked pane Cmd+Option+Up / Down Alt+Up / Down
Cycle through panes Cmd+[ / ] Ctrl+Shift+Left / Right
Close the focused pane and its shell Cmd+W Ctrl+Shift+W
Rename the focused pane Cmd+Shift+R Ctrl+Shift+R
Copy selection / paste Cmd+C / Cmd+V Ctrl+Shift+C / Ctrl+Shift+V
Quit the GUI and keep sessions running Cmd+Q Window ×
Scroll one page Shift+PageUp / PageDown Shift+PageUp / PageDown
Jump to oldest history / live screen Shift+Home / End Shift+Home / End

Click a tab to switch, + to create a tab, or a collapsed pane title to expand it. Hover over any tab to show its × button. On a local tab, it closes the tab and all its shells. On a remote tab, it detaches the SSH session. Drag, double-click, or triple-click to select text, a word, or a line. Scroll with the mouse wheel or touchpad. Closing the window detaches the GUI and keeps the server sessions running.

Choose Rename tab in the palette to edit the selected tab's name. When renaming a pane or tab, press Enter to save or Escape to cancel. Saving a blank name restores automatic naming.

On Linux, the Alt shortcuts follow Zellij’s shared map, with Alt+\ from its locked map. Alt+Shift+N and Alt+Shift+Right also create a tab. On macOS, Option+Up/Down also focus stacked panes, and Option+Shift+Up/Down insert them.

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, including collapsed panes. 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. Unbound Alt/Option character keys send Meta. On a Mac keyboard, Option+Delete (⌥⌫) sends Meta+Backspace, which deletes the preceding word in Bash and Zsh’s Emacs keymaps. Option+B/F move by word. Shift+Left/Right carry their xterm Shift modifier so a CLI can bind them. Plain Ctrl shortcuts such as Ctrl+C and Ctrl+D reach the terminal. 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.

Tabs use a manual name when set; otherwise they inherit the selected pane's effective name. Use Rename tab in the command palette to edit the tab label inline. Enter saves; Escape or clicking elsewhere cancels. Saving an empty name or choosing Use automatic tab name restores inheritance immediately. Tab names are server-owned and survive pane switches, shell exits within the tab, and client reconnects.

Tabs form the horizontal dimension; each column within a tab has an ordered vertical stack. One pane per stack is expanded, with the other titles above and below it. Creating or switching stacked panes uses the same curve as tab changes, with vertical motion. Vertical navigation stops at the first/last pane. Side-by-side splits create independent columns, each with its own stack. Long collapsed-title lists scroll, leaving room for the expanded terminal.

Stack order, expanded panes, titles, and all shells live on the server and survive GUI detach/reattach. Collapsed shells keep running; their grids are sent only when expanded, and their output does not redraw unchanged visible grids.

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. When the last pane exits or the last tab closes, every window showing that session closes. Windows showing other sessions stay open.

Each session has its own tabs, panes, focus, and scrollback. Windows attached to the same session share those and the underlying PTY grid. Each window keeps its own text size, and the focused window sets the grid dimensions. Tabs and panes survive GUI disconnects and stay in server memory until the shells exit or the server stops.

Appearance

The inset terminal surface and titlebar use the dark Sybil palette shared by Huayra, Attractor, and Sybil. Local tabs have a purple accent. SSH tabs have a teal accent and show the destination hostname beneath their title. Pane headers use teal, with a matching border around the active pane. 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. The default font size is 15 logical pixels. Row height scales with font size and rounds to the nearest logical pixel. The text-size shortcuts resize all terminals in the focused window, including panes opened there later. Each new window starts at the default size. 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 platform-specific GUI launch
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

On Linux, 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.

Dependencies are pinned to published releases, with no local Alacritty checkout required. The vendored GPUI patch restarts Wayland painting when asynchronous output invalidates an idle window; active frames remain paced by the compositor. The 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

# Optional regression check with Weston installed (headless backend, fake seat):
cargo build --locked
python3 scripts/check-wayland-idle.py

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.

The Wayland regression check creates a private compositor and server. With the cursor hidden, it verifies a quiet window does not keep repainting, then sends terminal output and checks that painting resumes without a screenshot, resize, or desktop input to wake the compositor. It fails on unpatched GPUI 0.2.2.

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. Tab-name tests cover manual precedence, selected-pane inheritance, resets, and reconnects. Editor tests cover Unicode selection and composition; protocol tests pin the previous versions’ shutdown handshakes. Stack tests cover insertion, navigation, hidden output, reattachment, exit cleanup, and command bursts without intervening snapshots.

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. New live checks cover palette search/submenus and input isolation, Zellij navigation bindings, stack insertion in both directions, collapsed-pane focus, exit cleanup, and stack reattachment. A second client's focus changes preserve palette input. These checks cover Linux Wayland.

Current limits include no arbitrary split trees or floating panes, shared per-session 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.

S
Description
Terminal
Readme
5.8 MiB
Languages
Rust 99.1%
Python 0.9%