ezpn 0.11.0

Dead simple terminal pane splitting — ezpn 2 3 gives you a 2x3 grid of shells
ezpn-0.11.0 is not a library.

Why ezpn?

$ ezpn                # split your terminal, instantly
$ ezpn 2 3            # 2x3 grid of shells
$ ezpn -l dev         # preset layout

No config files, no setup, no learning curve. Sessions persist in the background — Ctrl+B d to detach, ezpn a to come back.

In a project, drop .ezpn.toml in your repo and run ezpn — everyone gets the same workspace:

[session]
name = "myproject"           # pin the session name (collisions become myproject-1, -2...)

[workspace]
layout = "7:3/1:1"
persist_scrollback = true    # scrollback survives detach/reattach

[[pane]]
name = "editor"
command = "nvim ."

[[pane]]
name = "server"
command = "npm run dev"
restart = "on_failure"
env = { NODE_ENV = "${env:NODE_ENV}", DB_URL = "${file:.env.local}" }

[[pane]]
name = "tests"
command = "npm test -- --watch"

[[pane]]
name = "logs"
command = "tail -f logs/app.log"

$ ezpn         # reads .ezpn.toml, starts everything
$ ezpn doctor  # validates env interpolation + secret refs before you run

No tmuxinator. No YAML. Just a TOML file in your repo.

Install

cargo install ezpn

Or grab a prebuilt binary from the latest release — ezpn-x86_64-unknown-linux-gnu.tar.gz, ezpn-x86_64-apple-darwin.tar.gz, or ezpn-aarch64-apple-darwin.tar.gz.

git clone https://github.com/subinium/ezpn
cd ezpn && cargo install --path .

Quick Start

ezpn                  # 2 panes (or load .ezpn.toml if present)
ezpn 2 3              # 2x3 grid
ezpn -l dev           # Layout preset (dev, monitor, quad, stack, trio...)
ezpn -e 'cmd1' -e 'cmd2'   # Per-pane commands

Sessions

Ctrl+B d               # Detach (session keeps running)
ezpn a                 # Reattach to most recent session
ezpn a myproject       # Reattach by name
ezpn ls                # List active sessions
ezpn kill myproject    # Kill a session
ezpn --new             # Force a new session even if one already exists for $PWD

Session names default to basename($PWD). Collisions are resolved deterministically — repo → repo-1 → repo-2 (dead sockets are reaped during the scan). Pin a name in .ezpn.toml via [session].name = "...".

Tabs

Ctrl+B c               # New tab
Ctrl+B n / p           # Next / previous tab
Ctrl+B 0-9             # Jump to tab

All tmux keys work — Ctrl+B % to split, Ctrl+B x to close, Ctrl+B [ for copy mode.

Features
Zero config Works out of the box. No rc files needed.
Layout presets dev, ide, monitor, quad, stack, main, trio
Session persistence Detach/attach like tmux. Background daemon keeps processes alive. Sub-50 ms cold attach.
Scrollback persist Opt-in persist_scrollback survives detach/reattach (gzip+bincode in v3 snapshots).
Tabs tmux-style windows with tab bar and mouse click switching.
Mouse-first Click to focus, drag to resize, scroll for history, drag to select & copy.
Copy mode Vi keys, visual selection, incremental display-width search, OSC 52 clipboard.
Command palette Ctrl+B : with tmux-compatible commands.
Broadcast mode Type in all panes simultaneously.
Project config .ezpn.toml per project — layout, commands, env vars, auto-restart.
Env interpolation ${HOME}, ${env:VAR}, ${file:.env.local}, ${secret:keychain:KEY} in pane env.
Themes TOML palette + 4 builtins (tokyo-night, gruvbox-dark, solarized-dark/-light).
Hot reload Ctrl+B r reloads ~/.config/ezpn/config.toml without detaching.
Borderless mode ezpn -b none for maximum screen space.
Kitty keyboard Shift+Enter, Ctrl+Arrow, Alt+Char (CSI u / RFC 3665) — modified keys work correctly.
CJK/Unicode Proper width calculation for Korean, Chinese, Japanese, and emoji.
Crash isolation One panicking pane can't take down the daemon (signal-safe SIGTERM/SIGCHLD handling).

Layout Presets

ezpn -l dev       # 7:3 — main + side
ezpn -l ide       # 7:3/1:1 — editor + sidebar + 2 bottom
ezpn -l monitor   # 1:1:1 — 3 equal columns
ezpn -l quad      # 2x2 grid
ezpn -l stack     # 1/1/1 — 3 stacked rows
ezpn -l main      # 6:4/1 — wide top pair + full bottom
ezpn -l trio      # 1/1:1 — full top + 2 bottom

Custom ratios: ezpn -l '7:3/5:5'

Project Config

Drop .ezpn.toml in your project root and run ezpn. That's it.

Per-pane options: command, cwd, name, env, restart (never/on_failure/always), shell

ezpn init              # Generate .ezpn.toml template
ezpn from Procfile     # Import from Procfile
ezpn doctor            # Validate config + env interpolation, exit non-zero on missing refs

Env interpolation

Pane env values support four reference forms:

[[pane]]
command = "npm run dev"
env = {
  HOME       = "${HOME}",                    # process env
  NODE_ENV   = "${env:NODE_ENV}",            # explicit env
  DB_URL     = "${file:.env.local}",         # dotenv-style file lookup
  GH_TOKEN   = "${secret:keychain:GH_TOKEN}",# macOS Keychain (Linux: secret-tool)
}

.env.local next to .ezpn.toml is auto-merged and overrides [env]. ${secret:keychain:KEY} falls back to ${env:KEY} with a warning when the OS keychain isn't available. Recursion is depth-capped at 8 to catch cycles.

Themes

# .ezpn.toml or ~/.config/ezpn/config.toml
theme = "tokyo-night"   # default | tokyo-night | gruvbox-dark | solarized-dark | solarized-light

User themes load from ~/.config/ezpn/themes/<name>.toml. ezpn auto-detects $COLORTERM / $TERM and downgrades to 256 or 16 colors when truecolor isn't supported.

border = rounded            # single | rounded | heavy | double | none
shell = /bin/zsh
scrollback = 10000
status_bar = true
tab_bar = true
prefix = b                  # prefix key (Ctrl+<key>)
theme = default             # default | tokyo-night | gruvbox-dark | solarized-dark | solarized-light
persist_scrollback = false  # save scrollback into auto-snapshots (off by default)

Settings panel changes (Ctrl+B Shift+,) are persisted atomically. Reload from disk with Ctrl+B r.

Keybindings

Direct shortcuts:

Key Action
Ctrl+D Split horizontal
Ctrl+E Split vertical
Ctrl+N Next pane
F2 Equalize sizes

Prefix mode (Ctrl+B, then):

Key Action
% / " Split H / V
o / Arrow Navigate panes
x Close pane
z Zoom toggle
R Resize mode
[ Copy mode
B Broadcast
: Command palette
r Reload config
d Detach session
? Help

Tabs:

Key Action
Ctrl+B c New tab
Ctrl+B n / p Next / previous tab
Ctrl+B 0-9 Jump to tab
Ctrl+B , Rename tab
Ctrl+B & Close tab

Panes:

Key Action
Ctrl+B { / } Swap pane prev / next
Ctrl+B E / Space Equalize
Ctrl+B s Toggle status bar
Ctrl+B q Pane numbers + quick jump

Copy mode (Ctrl+B [):

Key Action
h j k l Move cursor
w / b Next / previous word
0 / $ / ^ Line start / end / first non-blank
g / G Top / bottom of scrollback
Ctrl+U / Ctrl+D Half page up / down
v Character selection
V Line selection
y / Enter Copy and exit
/ / ? Search forward / backward
n / N Next / previous match
q / Esc Exit

Mouse:

Action Effect
Click pane Focus
Double-click Zoom toggle
Click tab Switch tab
Click [x] Close pane
Drag border Resize
Drag text Select + copy
Scroll wheel Scrollback history

macOS note: Alt+Arrow for directional navigation requires Option as Meta (iTerm2: Preferences > Profiles > Keys > Esc+).

Ctrl+B : opens the command prompt. All tmux aliases are supported.

split / split-window         Split horizontally
split -v                     Split vertically
new-tab / new-window         Create new tab
next-tab / prev-tab          Switch tabs
close-pane / kill-pane       Close active pane
close-tab / kill-window      Close current tab
rename-tab <name>            Rename tab
layout <spec>                Change layout
equalize / even              Equalize pane sizes
zoom                         Toggle zoom
broadcast                    Toggle broadcast mode

ezpn vs. tmux vs. Zellij

tmux Zellij ezpn
Setup .tmux.conf required KDL config Zero config
First use Empty screen Tutorial mode ezpn
Sessions tmux a zellij a ezpn a
Project config tmuxinator (gem) — .ezpn.toml built-in
Broadcast :setw synchronize-panes — Ctrl+B B
Auto-restart — — restart = "always"
Kitty keyboard No Yes Yes
Plugin system — WASM —
Ecosystem Massive (30 years) Growing New

Choose ezpn if you want terminal splits that just work. Choose tmux if you need deep scripting and plugin ecosystem. Choose Zellij if you want a modern UI with WASM plugins.

CLI Reference

ezpn [ROWS COLS]         Start with grid layout
ezpn -l <PRESET>         Start with layout preset
ezpn -e <CMD> [-e ...]   Per-pane commands
ezpn -S <NAME>           Named session
ezpn -b <STYLE>          Border style (single/rounded/heavy/double/none)
ezpn --new               Force a new session (skip auto-attach to existing)
ezpn a [NAME]            Attach to session
ezpn ls                  List sessions
ezpn kill [NAME]         Kill session
ezpn rename OLD NEW      Rename session
ezpn init                Generate .ezpn.toml template
ezpn from <FILE>         Import from Procfile
ezpn doctor              Validate .ezpn.toml + env interpolation

License

MIT