zmx - session persistence for terminal sessions

features

demos

install

binaries

homebrew

mise-en-place

NixOS / nixpkgs

packages (unofficial)

src

usage

shell prompt

fish

bash and zsh

powerlevel10k zsh theme

oh-my-posh

Starship

shell completion

bash

zsh

fish

session picker

Alternative: gentle hint (server use)

session prefix

philosophy

ssh workflow

Try it out quickly

Configure it for regular use

socket file location

permissions

debugging

a smol contract

known issues

impl

libghostty-vt

prior art

shpool

abduco

comparison

community tools

zmx

Session attach/detach for the terminal.

Docs<br>You might not need tmux<br>Sponsored by pico.sh

features #

Persist terminal shell sessions

Ability to attach and detach from a shell session without it being killed

Native terminal scrollback

Multiple clients can connect to the same session

Re-attaching to a session restores previous terminal state and output

Send commands to a session without attaching to it

Print scrollback history of a terminal session in plain text

Works on mac and linux

This project does NOT provide windows, tabs, or splits

demos #

zmx - intro

zmx - ai portal

install #

binaries #

https://zmx.sh/a/zmx-0.7.0-linux-aarch64.tar.gz

https://zmx.sh/a/zmx-0.7.0-linux-x86_64.tar.gz

https://zmx.sh/a/zmx-0.7.0-macos-aarch64.tar.gz

https://zmx.sh/a/zmx-0.7.0-macos-x86_64.tar.gz

homebrew #

1brew install neurosnap/tap/zmx<br>mise-en-place #

1mise use zmx<br>NixOS / nixpkgs #

Run immediately without installation:

1nix run github:NixOS/nixpkgs/nixpkgs-unstable#zmx<br>2# or build main yourself<br>3nix run github:neurosnap/zmx<br>Start a shell with zmx available while it runs:

1nix shell github:NixOS/nixpkgs/nixpkgs-unstable#zmx<br>2# or built main yourself<br>3nix run github:neurosnap/zmx<br>packages (unofficial) #

Alpine Linux

Arch AUR tracking releases

Arch AUR tracking git

openSUSE Tumbleweed

Gentoo (overlay)

zmx-rpm packaging

src #

Requires zig v0.16

Clone the repo

Run build cmd

Be sure to add ~/.local/bin to your PATH:

1zig build -Doptimize=ReleaseSafe --prefix ~/.local<br>usage #

[!IMPORTANT]<br>We recommend closing the terminal window to detach from the session but you can also press ctrl+\ or run zmx detach.

Run zmx help for more information on usage, with examples.

Usage: zmx [args...]

Commands:<br>[a]ttach [command...] Attach to session, creating if needed<br>[r]un [-d] [command...] Send command without attaching<br>[s]end Send raw input to session PTY<br>[p]rint Inject text into session display<br>[wr]ite Write stdin to file_path through the session<br>[d]etach Detach all clients (ctrl+\\ for current client)<br>[l]ist|ls [--short|--where k=v] List active sessions<br>[g]et Get session labels<br>set k=v ... Set session labels<br>[un]set key ... Remove session labels<br>[cl]ear Clear all session labels<br>[k]ill ... [--force] Kill session and all attached clients<br>[hi]story [--vt|--html] Output session scrollback<br>[w]ait ... Wait for session tasks to complete<br>[t]ail ... Follow session output<br>[c]ompletions Shell completions (bash, zsh, fish, nu)<br>[v]ersion Show version and metadata (socket dir, log dir)<br>[h]elp Show this help

shell prompt #

When you attach to a zmx session, we don't provide any indication that you are inside zmx. We do provide an environment variable ZMX_SESSION which contains the session name.

We recommend checking for that env var inside your prompt and displaying some indication there.

fish #

Place this file in ~/.config/fish/config.fish:

1functions -c fish_prompt _original_fish_prompt 2>/dev/null<br>3function fish_prompt --description 'Write out the prompt'<br>4 if set -q ZMX_SESSION<br>5 echo -n "[$ZMX_SESSION] "<br>6 end<br>7 _original_fish_prompt<br>8end<br>bash and zsh #

Depending on the shell, place this in either .bashrc or .zshrc:

1if [[ -n $ZMX_SESSION ]]; then<br>2 export PS1="[$ZMX_SESSION] ${PS1}"<br>3fi<br>powerlevel10k zsh theme #

powerlevel10k is a theme for zsh that overwrites the default prompt statusline.

Place this in .zshrc:

1function prompt_my_zmx_session() {<br>2 if [[ -n $ZMX_SESSION ]]; then<br>3 p10k segment -b '%k' -f '%f' -t "[$ZMX_SESSION]"<br>4 fi<br>5}<br>6POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS+=my_zmx_session<br>oh-my-posh #

oh-my-posh is a popular shell themeing and prompt engine. This code will display an icon and session name as part of the prompt if (and only if) you have zmx active:

1[[blocks.segments]]<br>2 template = '{{ if .Env.ZMX_SESSION }} {{ .Env.ZMX_SESSION }}{{ end }}'<br>3 foreground = 'p:orange'<br>4 background = 'p:black'<br>5 type = 'text'<br>6 style = 'plain'<br>Starship #

Starship is a popular shell themeing and prompt engine. This code will display an icon and session name as part of the prompt if (and only if) you have zmx active:

1format = """<br>2${env_var.ZMX_SESSION}\<br>3...<br>4"""<br>6[env_var.ZMX_SESSION]<br>7symbol = " "<br>8format = "[$symbol$env_value]($style) "<br>9description = "zmx session name"<br>10style = "bold magenta"<br>shell completion #

Shell auto-completion for zmx commands and session names can be enabled using the completions subcommand....