408 lines
21 KiB
Markdown
408 lines
21 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. 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:
|
||
|
||
```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`.
|
||
|
||
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.
|
||
|
||
```sh
|
||
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.
|
||
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 --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`.
|
||
|
||
```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.
|
||
|
||
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.
|
||
|
||
```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 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. 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. 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](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.
|