2026-11-17 01:08:35 -08:00
|
|
|
|
# psyTerm
|
2026-11-17 00:12:24 -08:00
|
|
|
|
|
2026-11-17 11:49:40 -08:00
|
|
|
|
A terminal and multiplexer for macOS and Linux (Wayland), built with [GPUI 0.2.2](https://gpui.rs/)
|
2026-11-17 01:08:35 -08:00
|
|
|
|
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
|
2026-11-17 14:50:29 -08:00
|
|
|
|
detaches it. Run `psyterm --attach` to return to the running shells, or
|
|
|
|
|
|
`psyterm` to start a fresh session.
|
2026-11-17 00:12:24 -08:00
|
|
|
|
|
|
|
|
|
|
## Build and run
|
|
|
|
|
|
|
2026-11-17 11:49:40 -08:00
|
|
|
|
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
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-11-17 18:12:22 -08:00
|
|
|
|
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.
|
2026-11-17 11:49:40 -08:00
|
|
|
|
|
|
|
|
|
|
### Linux
|
|
|
|
|
|
|
|
|
|
|
|
Use Linux 5.3 or newer. GUI processes require a running Wayland desktop and
|
|
|
|
|
|
a working Vulkan driver.
|
2026-11-17 01:08:35 -08:00
|
|
|
|
The server and SSH bridge do not initialize GPUI, Wayland, or Vulkan, although
|
|
|
|
|
|
the shared executable still needs its dynamically linked libraries installed.
|
2026-11-17 00:12:24 -08:00
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-11-17 01:08:35 -08:00
|
|
|
|
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.
|
2026-11-17 00:12:24 -08:00
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
|
cargo run --locked
|
2026-11-17 01:08:35 -08:00
|
|
|
|
|
|
|
|
|
|
cargo build --locked --release
|
|
|
|
|
|
./target/release/psyterm
|
2026-11-17 00:12:24 -08:00
|
|
|
|
```
|
|
|
|
|
|
|
2026-11-17 01:08:35 -08:00
|
|
|
|
The default command starts or reuses a local server, asks its zygote to fork a
|
2026-11-17 14:50:29 -08:00
|
|
|
|
GUI, and returns. Each invocation starts an independent session unless you pass
|
|
|
|
|
|
`--attach`.
|
2026-11-17 01:08:35 -08:00
|
|
|
|
|
2026-11-17 18:12:22 -08:00
|
|
|
|
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
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-11-17 11:49:40 -08:00
|
|
|
|
### Shells and sessions
|
|
|
|
|
|
|
2026-11-17 18:11:37 -08:00
|
|
|
|
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
|
2026-11-17 16:20:54 -08:00
|
|
|
|
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.
|
2026-11-17 14:50:29 -08:00
|
|
|
|
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
|
2026-11-17 11:49:40 -08:00
|
|
|
|
`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
|
2026-11-17 01:08:35 -08:00
|
|
|
|
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.
|
|
|
|
|
|
|
2026-11-17 14:50:29 -08:00
|
|
|
|
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.
|
2026-11-17 01:08:35 -08:00
|
|
|
|
Finish any running work first, since shutdown ends its sessions, then launch
|
|
|
|
|
|
`psyterm` again to start the updated server.
|
|
|
|
|
|
|
|
|
|
|
|
## Commands and connections
|
|
|
|
|
|
|
|
|
|
|
|
| Command | Behavior |
|
|
|
|
|
|
| --- | --- |
|
2026-11-17 14:50:29 -08:00
|
|
|
|
| `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 |
|
2026-11-17 16:15:28 -08:00
|
|
|
|
| `psyterm --remote --attach` | Reopen the last remote session you detached |
|
2026-11-17 14:50:29 -08:00
|
|
|
|
| `psyterm --remote user@host --attach [ID]` | Reattach to an existing session on the SSH host |
|
2026-11-17 18:12:22 -08:00
|
|
|
|
| `psyterm --gui` | Open a window in the shared macOS app or run a Linux GUI in the current process |
|
2026-11-17 14:50:29 -08:00
|
|
|
|
| `psyterm --list` | Show local sessions, attached window counts, tabs, and panes |
|
2026-11-17 01:08:35 -08:00
|
|
|
|
| `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,
|
2026-11-17 11:49:40 -08:00
|
|
|
|
user-owned parent directory with mode `0700`.
|
2026-11-17 00:12:24 -08:00
|
|
|
|
|
|
|
|
|
|
```sh
|
2026-11-17 11:49:40 -08:00
|
|
|
|
socket_dir=$(mktemp -d /tmp/psyterm.XXXXXXXX)
|
|
|
|
|
|
cargo run --locked -- --socket "$socket_dir/server.sock"
|
2026-11-17 00:12:24 -08:00
|
|
|
|
```
|
|
|
|
|
|
|
2026-11-17 11:49:40 -08:00
|
|
|
|
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`.
|
2026-11-17 01:08:35 -08:00
|
|
|
|
|
2026-11-17 14:50:29 -08:00
|
|
|
|
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.
|
|
|
|
|
|
|
2026-11-17 16:15:28 -08:00
|
|
|
|
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`.
|
|
|
|
|
|
|
2026-11-17 16:20:54 -08:00
|
|
|
|
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.
|
2026-11-17 16:15:28 -08:00
|
|
|
|
|
2026-11-17 14:50:29 -08:00
|
|
|
|
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.
|
2026-11-17 00:12:24 -08:00
|
|
|
|
|
|
|
|
|
|
```sh
|
2026-11-17 14:50:29 -08:00
|
|
|
|
PSYTERM_REMOTE_BIN=/home/me/bin/psyterm psyterm --remote me@workstation
|
2026-11-17 00:12:24 -08:00
|
|
|
|
```
|
|
|
|
|
|
|
2026-11-17 01:08:35 -08:00
|
|
|
|
SSH starts `psyterm --bridge` on the remote host, which starts or reuses that
|
2026-11-17 14:50:29 -08:00
|
|
|
|
host's server. SSH carries input and terminal updates over its standard streams.
|
|
|
|
|
|
To end remote sessions,
|
2026-11-17 01:08:35 -08:00
|
|
|
|
run `psyterm --shutdown` on the remote host, for example through SSH.
|
2026-11-17 00:12:24 -08:00
|
|
|
|
|
2026-11-17 01:08:35 -08:00
|
|
|
|
## Controls
|
2026-11-17 00:12:24 -08:00
|
|
|
|
|
2026-11-17 14:49:35 -08:00
|
|
|
|
| Action | macOS | Linux |
|
|
|
|
|
|
| --- | --- | --- |
|
2026-11-17 14:50:29 -08:00
|
|
|
|
| Open a new window and session | Cmd+N | Ctrl+Shift+N |
|
2026-11-17 14:49:35 -08:00
|
|
|
|
| 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 |
|
2026-11-17 16:10:18 -08:00
|
|
|
|
| Create a tab | Cmd+T or Option+Shift+Left / Right | Ctrl+Shift+T |
|
2026-11-17 14:49:35 -08:00
|
|
|
|
| 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 |
|
2026-11-17 16:10:18 -08:00
|
|
|
|
| Focus the adjacent pane or tab | Option+Left / Right or Cmd+Option+Left / Right | Alt+Left / Right |
|
2026-11-17 14:49:35 -08:00
|
|
|
|
| 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 |
|
2026-11-17 00:12:24 -08:00
|
|
|
|
|
2026-11-17 14:49:35 -08:00
|
|
|
|
Click a tab to switch, `+` to create a tab, or a collapsed pane title to expand it.
|
2026-11-17 16:15:28 -08:00
|
|
|
|
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.
|
2026-11-17 14:49:35 -08:00
|
|
|
|
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.
|
|
|
|
|
|
|
2026-11-17 16:10:18 -08:00
|
|
|
|
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.
|
2026-11-17 01:32:41 -08:00
|
|
|
|
|
2026-11-17 01:29:05 -08:00
|
|
|
|
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
|
2026-11-17 02:04:41 -08:00
|
|
|
|
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.
|
2026-11-17 01:29:05 -08:00
|
|
|
|
|
2026-11-17 16:10:18 -08:00
|
|
|
|
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.
|
2026-11-17 01:08:35 -08:00
|
|
|
|
Alternate-screen applications receive shifted navigation; the wheel sends
|
|
|
|
|
|
arrow keys when the application enables alternate scrolling.
|
2026-11-17 00:12:24 -08:00
|
|
|
|
|
2026-11-17 01:08:35 -08:00
|
|
|
|
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.
|
2026-11-17 00:12:24 -08:00
|
|
|
|
|
2026-11-17 08:56:02 -08:00
|
|
|
|
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.
|
|
|
|
|
|
|
2026-11-17 02:04:41 -08:00
|
|
|
|
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.
|
|
|
|
|
|
|
2026-11-17 01:08:35 -08:00
|
|
|
|
When a shell exits, its pane closes automatically. An empty tab closes too,
|
2026-11-17 18:13:06 -08:00
|
|
|
|
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.
|
2026-11-17 00:12:24 -08:00
|
|
|
|
|
2026-11-17 14:50:29 -08:00
|
|
|
|
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.
|
2026-11-17 01:08:35 -08:00
|
|
|
|
|
|
|
|
|
|
## Appearance
|
|
|
|
|
|
|
|
|
|
|
|
The inset terminal surface and titlebar use the dark Sybil palette shared by
|
2026-11-17 14:51:14 -08:00
|
|
|
|
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.
|
2026-11-17 01:08:35 -08:00
|
|
|
|
|
2026-11-17 01:24:47 -08:00
|
|
|
|
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.
|
|
|
|
|
|
|
2026-11-17 01:08:35 -08:00
|
|
|
|
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,
|
2026-11-17 18:12:04 -08:00
|
|
|
|
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.
|
2026-11-17 14:49:35 -08:00
|
|
|
|
Each new window starts at the default size. Rendering supports ANSI/256
|
2026-11-17 01:08:35 -08:00
|
|
|
|
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 |
|
2026-11-17 00:12:24 -08:00
|
|
|
|
| --- | --- |
|
2026-11-17 01:08:35 -08:00
|
|
|
|
| `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 |
|
2026-11-17 11:49:40 -08:00
|
|
|
|
| `launcher.rs` | Server startup, private paths, lifecycle locks, and platform-specific GUI launch |
|
2026-11-17 01:29:05 -08:00
|
|
|
|
| `terminal.rs` | Snapshot-only GUI workspace and panes, command dispatch, focus, and animation scheduling |
|
2026-11-17 01:32:41 -08:00
|
|
|
|
| `commands.rs`, `bindings.rs`, `palette.rs` | Extensible command metadata, optional shortcuts, searchable nested menus |
|
2026-11-17 01:08:35 -08:00
|
|
|
|
| `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 |
|
2026-11-17 00:12:24 -08:00
|
|
|
|
|
2026-11-17 11:49:40 -08:00
|
|
|
|
On Linux, the server starts the zygote on demand and manages its lifetime. The zygote
|
2026-11-17 01:08:35 -08:00
|
|
|
|
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.
|
2026-11-17 00:12:24 -08:00
|
|
|
|
|
2026-11-17 01:29:05 -08:00
|
|
|
|
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.
|
|
|
|
|
|
|
2026-11-17 01:08:35 -08:00
|
|
|
|
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.
|
2026-11-17 00:12:24 -08:00
|
|
|
|
|
2026-11-17 02:08:15 -08:00
|
|
|
|
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
|
2026-11-17 01:08:35 -08:00
|
|
|
|
Linux `ENOATTR` compatibility issue. `Cargo.lock` records dependency versions.
|
2026-11-17 00:12:24 -08:00
|
|
|
|
|
2026-11-17 01:08:35 -08:00
|
|
|
|
## Development
|
2026-11-17 00:12:24 -08:00
|
|
|
|
|
2026-11-17 01:08:35 -08:00
|
|
|
|
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.
|
2026-11-17 00:12:24 -08:00
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
|
cargo fmt --check
|
|
|
|
|
|
cargo check --locked
|
|
|
|
|
|
cargo test --locked
|
|
|
|
|
|
cargo clippy --locked --all-targets -- -D warnings
|
2026-11-17 01:08:35 -08:00
|
|
|
|
|
|
|
|
|
|
RUST_LOG=psyterm::timing=debug cargo run --locked -- --gui
|
2026-11-17 02:08:15 -08:00
|
|
|
|
|
|
|
|
|
|
# Optional regression check with Weston installed (headless backend, fake seat):
|
|
|
|
|
|
cargo build --locked
|
|
|
|
|
|
python3 scripts/check-wayland-idle.py
|
2026-11-17 00:12:24 -08:00
|
|
|
|
```
|
|
|
|
|
|
|
2026-11-17 01:08:35 -08:00
|
|
|
|
`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.
|
2026-11-17 00:12:24 -08:00
|
|
|
|
|
2026-11-17 02:08:15 -08:00
|
|
|
|
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.
|
|
|
|
|
|
|
2026-11-17 01:08:35 -08:00
|
|
|
|
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,
|
2026-11-17 08:56:02 -08:00
|
|
|
|
program/manual name precedence, title resets, and rename persistence. Tab-name
|
|
|
|
|
|
tests cover manual precedence, selected-pane inheritance, resets, and reconnects. Editor
|
2026-11-17 01:08:35 -08:00
|
|
|
|
tests cover Unicode selection and composition; protocol tests pin the previous
|
2026-11-17 02:04:41 -08:00
|
|
|
|
versions’ shutdown handshakes. Stack tests cover insertion, navigation, hidden
|
2026-11-17 02:08:15 -08:00
|
|
|
|
output, reattachment, exit cleanup, and command bursts without intervening snapshots.
|
2026-11-17 01:08:35 -08:00
|
|
|
|
|
|
|
|
|
|
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.
|
2026-11-17 02:04:41 -08:00
|
|
|
|
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
|
2026-11-17 11:49:40 -08:00
|
|
|
|
palette input. These checks cover Linux Wayland.
|
2026-11-17 01:08:35 -08:00
|
|
|
|
|
2026-11-17 14:50:29 -08:00
|
|
|
|
Current limits include no arbitrary split trees or floating panes, shared per-session
|
2026-11-17 02:04:41 -08:00
|
|
|
|
viewport state, no disk-restored sessions, no configuration files, no application mouse reporting,
|
2026-11-17 01:08:35 -08:00
|
|
|
|
no Kitty keyboard protocol, no OSC 52 clipboard access, and no clickable links.
|