Move terminal sessions, tabs, panes, and state into a persistent headless server with local socket and SSH clients. Launch GUIs through a managed single-threaded zygote while keeping rendering responsive. Add animated cursors, themed chrome, teal pane focus outlines, uniform tabs, and middle-truncated names. Support program/CWD titles, manual renaming, home-directory abbreviation, and automatic pane/tab removal when shells exit. Document the process architecture, controls, and third-party cursor sources. Validated with 57 tests, strict Clippy, and live Wayland checks.
236 lines
12 KiB
Markdown
236 lines
12 KiB
Markdown
# psyTerm
|
||
|
||
A Wayland terminal and multiplexer 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; 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:
|
||
|
||
```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. 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`:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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 |
|
||
| --- | --- |
|
||
| Click a tab | Switch the server's active tab |
|
||
| `+` or Ctrl+Shift+T | Create a tab |
|
||
| Ctrl+Shift+D | Add a pane beside the focused pane |
|
||
| 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 |
|
||
|
||
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.
|
||
|
||
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 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, input, focus, and animation scheduling |
|
||
| `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.
|
||
|
||
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](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
|
||
```
|
||
|
||
`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.
|