Create independent sessions and open SSH sessions in adjacent tabs

Start new windows with a fresh shell and add explicit session selection through --attach. Route in-pane SSH launches back to the originating session, preserving remote shells and tab order across local detach and reattach.
This commit is contained in:
James Magahern
2026-11-17 14:50:29 -08:00
parent 10fa542937
commit d980799648
14 changed files with 2064 additions and 302 deletions
+44 -25
View File
@@ -4,7 +4,8 @@ A terminal and multiplexer for macOS and Linux (Wayland), built with [GPUI 0.2.2
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.
detaches it. Run `psyterm --attach` to return to the running shells, or
`psyterm` to start a fresh session.
## Build and run
@@ -35,8 +36,8 @@ 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 and connect to the same local server. Use `open -n`
with the app path for another window. The bundle's
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
@@ -76,12 +77,19 @@ cargo build --locked --release
```
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.
GUI, and returns. Each invocation starts an independent session unless you pass
`--attach`.
### Shells and sessions
The first attachment to an empty server creates a shell in the server's startup
directory. Shells inherit the server's environment and receive
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`.
@@ -93,8 +101,9 @@ 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 4. An older server must be restarted before
attaching; `psyterm --shutdown` can stop servers using versions 1–3.
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.
@@ -102,10 +111,12 @@ Finish any running work first, since shutdown ends its sessions, then launch
| Command | Behavior |
| --- | --- |
| `psyterm` | Open a local window attached to the server |
| `psyterm --remote user@host` | Open a local GUI connected to the remote server over SSH |
| `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` | Inspect tabs and panes in the running local server |
| `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 |
@@ -125,25 +136,33 @@ 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`.
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:
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 \
cargo run --locked -- --gui --remote me@workstation
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. stdout carries only framed protocol bytes. No TCP listener or
separate network authentication service is exposed. To end remote sessions,
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 |
@@ -216,11 +235,11 @@ 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.
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
@@ -336,6 +355,6 @@ 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-server
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.