Replace the window-wide connection badge with purple local tabs and teal SSH tabs. Show the SSH hostname below the remote tab title, including during tab renaming.
362 lines
18 KiB
Markdown
362 lines
18 KiB
Markdown
# psyTerm
|
||
|
||
A terminal and multiplexer for macOS and Linux (Wayland), built with [GPUI 0.2.2](https://gpui.rs/)
|
||
and [alacritty_terminal 0.26.0](https://docs.rs/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](https://github.com/zed-industries/zed/blob/main/script/bundle-mac).
|
||
|
||
```sh
|
||
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.
|
||
|
||
```sh
|
||
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. The bundle and CLI both open a GUI
|
||
in the launching process. Press Cmd+N for another window with its own session,
|
||
or run `open -n` with the app path. The bundle's
|
||
`Contents/MacOS/psyterm` executable also accepts the CLI commands below.
|
||
|
||
### 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:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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](https://github.com/zed-industries/zed/blob/main/script/linux).
|
||
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.
|
||
|
||
```sh
|
||
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`.
|
||
|
||
### Shells and sessions
|
||
|
||
Each new session starts with one tab and one shell. Windows opened with the
|
||
New Window shortcut start a fresh session in the focused pane’s directory on
|
||
the same host. Closing a window leaves its session available for reattachment.
|
||
To choose a session, run `psyterm --list` and pass its 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 user@host --attach [ID]` | Reattach to an existing session on the SSH host |
|
||
| `psyterm --gui` | Run the 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`.
|
||
|
||
```sh
|
||
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.
|
||
|
||
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.
|
||
|
||
```sh
|
||
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 | 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 | 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.
|
||
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.
|
||
|
||
Both platforms also support the Alt shortcuts from Zellij's `shared` map and
|
||
Alt+\ from its `locked` map. On macOS, Alt is the Option key.
|
||
Alt+Shift+N and Alt+Shift+Right also create a tab. Plain Ctrl shortcuts such
|
||
as Ctrl+C and Ctrl+D reach the terminal.
|
||
|
||
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. Ctrl+C, Ctrl+D and unbound 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.
|
||
|
||
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. After the
|
||
last shell exits, the window stays open with `+` available to start another tab.
|
||
|
||
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](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 with a 20-pixel line height by default. 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](vendor/gpui/PATCH.md) restarts Wayland painting
|
||
when asynchronous output invalidates an idle window; active frames remain paced
|
||
by the compositor. The [xattr patch](vendor/xattr/PATCH.md) 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.
|
||
|
||
```sh
|
||
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.
|