Merge pull request #199 from bnema/docs/concise-readme-palette-codes

docs(readme): condense overview and palette codes

commit: 2bffe86cbeb92bf97d5e9c8fcbc53b7b8489ac5e
author: bnema · 2mo ago · 2026-08-11 12:52 UTC
committer: GitHub · 2mo ago · 2026-08-11 12:52 UTC
merge of: fff724e + 504861a · diff against the first parent
signature: GPG UnverifiedB5690EEEBB952194 The key is unknown

1 file · +35 -76

M README.md +35 -76


@@ -18,98 +18,64 @@ Like tmux, minus the prefix key. Like mosh, minus mosh. One binary.</p>
18	18
19	19		## Install
20	20
21		-	Install a pre-built release on Linux x86_64/arm64 or macOS Apple silicon (arm64):
22		-
23	21		```sh
24	22		curl -fsSL https://raw.githubusercontent.com/bnema/vev/main/install.sh \| sh
	23	+	# Arch Linux: yay -S vev-bin
	24	+	# or: go install github.com/bnema/vev@latest
25	25		```
26	26
27		-	On Arch Linux, install [`vev-bin`](https://aur.archlinux.org/packages/vev-bin) from the AUR:
28		-
29		-	```sh
30		-	yay -S vev-bin
31		-	# or
32		-	paru -S vev-bin
33		-	```
34		-
35		-	Alternatively, build and install the binary with Go:
36		-
37		-	```sh
38		-	go install github.com/bnema/vev@latest
39		-	```
40		-
41		-	The default UI runs entirely from the `vev` binary. The pre-built installer also installs optional external bar anchors, which only take effect when configured in `~/.config/vev/config`.
	27	+	Releases support Linux x86_64/arm64 and macOS Apple silicon.
42	28
43	29		## Usage
44	30
45	31		```text
46	32		vev create an ephemeral session
47	33		vev new <name> create a named session
48		-	vev attach <name> attach to a session (alias: a)
49		-	vev attach user@host[:session] attach to a remote daemon over SSH
50		-	vev ls list local sessions
51		-	vev ls <host> list sessions on a known remote host
52		-	vev ls --all list local and remote sessions
53		-	vev host add <host> add a pinned remote host
54		-	vev host rm <host> remove a pinned remote host
55		-	vev host list list known remote hosts
56		-	vev kill <name> kill a session (--all kills everything)
	34	+	vev attach <name> attach to a local session (alias: a)
	35	+	vev attach user@host[:session] attach to a remote daemon
	36	+	vev ls [<host>\|--all] list sessions
	37	+	vev host add\|rm <host> manage remote hosts
	38	+	vev host list list remote hosts
	39	+	vev kill <name>\|--all kill sessions
57	40		```
58	41
59		-	The daemon starts on first use and exits with the last session. Ephemeral sessions are numbered, survive detach, and disappear with the daemon. Named sessions persist across daemon restarts and come back with their layout, recovered terminal transcript, and allowlisted processes.
60		-
61		-	A session may have multiple attachments. The session owns the PTYs, VT state, tabs, panes, shared PTY content geometry, and ordered mutations. Each attachment owns its window, view, copy mode, overlays, rendering/output state, and reconnect lifecycle, so attachments can focus different tabs or panes without changing one another's view. The latest valid, non-superseded attachment attach, resume, or resize claim controls shared PTY geometry; detaching that attachment falls back to the most recently claimed remaining valid attachment while preserving every attachment's own outer window.
	42	+	The daemon starts on first use and exits after the last session. Numbered sessions survive detach; named sessions also survive daemon restarts. See [durable-session recovery](docs/durable-session-recovery.md).
62	43
63		-	## Keys
	44	+	## Keys and palette
64	45
65		-	No prefix key; everything is Alt.
	46	+	No prefix key; bindings use Alt.
66	47
67	48		\| Key \| Action \|
68	49		\|---\|---\|
69	50		\| Alt+Space \| command palette \|
70		-	\| Alt+f \| floating terminal for the current tab \|
71		-	\| Alt+1 .. 9 \| switch tab \|
72		-	\| Alt+h/j/k/l, Alt+Arrow \| focus pane \|
	51	+	\| Alt+f \| floating terminal \|
	52	+	\| Alt+1 … 9 \| switch tab \|
	53	+	\| Alt+h/j/k/l or Alt+Arrow \| focus pane \|
73	54		\| Alt+a \| jump to a session needing attention \|
74	55
75		-	The palette does the rest: type a short code (`SPR` split right, `CNT` new tab, `SSP` session picker, ...) or fuzzy-search the command list. `MFP` (`Move pane to tab`) and `MAT` (`Move tab to session`) open live-destination pickers; the unbound pane consume/expel actions are discoverable there as `MPL` and `MPR`. Named active and stopped sessions are fuzzy-searchable for navigation, and selecting a stopped session resumes it. Scroll up with the mouse to enter scrollback; vim keys move, `v` selects, `y` copies via OSC 52.
76		-
77		-	## Remote attach
78		-
79		-	```sh
80		-	vev attach user@host[:session]
81		-	```
82		-
83		-	The client opens a direct connection to the selected remote daemon. UDP is the default: SSH bootstraps an authenticated UDP endpoint, then the session runs over that connection and resumes after sleep or Wi-Fi changes. vev must be installed on the remote. If your firewall only allows SSH, open the UDP range first (default `61000:61023`, override with `VEV_UDP_PORT_RANGE`):
84		-
85		-	```sh
86		-	sudo ufw allow 61000:61023/udp
87		-	```
88		-
89		-	Where UDP is not an option, set `VEV_REMOTE_TRANSPORT=stdio` to keep the direct connection inside SSH; this is an explicit transport choice. Every connection has a 15-second handshake deadline, and each command request has a 10-second deadline. Details in [docs/remote-resilience.md](docs/remote-resilience.md).
90		-
91		-	List sessions on a known host (OpenSSH resolves aliases from your SSH config):
	56	+	Type a code or fuzzy-search the palette. Common default codes:
92	57
93		-	```sh
94		-	vev ls arch
95		-	vev ls --all
96		-	```
	58	+	\| Code \| Action \| Code \| Action \|
	59	+	\|---\|---\|---\|---\|
	60	+	\| `CNT` \| new tab \| `CNS` \| new named session \|
	61	+	\| `SPR` / `SPL` \| split right / left \| `SPU` / `SPD` \| split up / down \|
	62	+	\| `STP` / `TFS` \| stack / toggle stack \| `TFP` \| floating terminal \|
	63	+	\| `MFP` / `MAT` \| move pane / tab \| `SSP` \| session picker \|
	64	+	\| `DET` \| detach \| `NTC` \| notifications \|
97	65
98		-	Remote session names appear as `session@host`. `vev ls --all` prints local sessions first, then remote sessions in host order. If one host fails, vev still prints the rest and exits non-zero.
	66	+	Scroll up to enter copy mode; use vim motions, `v` to select, and `y` to copy. All codes and bindings are configurable in [configuration](docs/configuration.md).
99	67
100		-	Manage pinned hosts in the unified host state file through the CLI:
	68	+	## Remote attach
101	69
102	70		```sh
103		-	vev host add arch
104		-	vev host rm arch
105		-	vev host list
	71	+	vev attach user@host[:session]
106	72		```
107	73
108		-	Successful attaches learn hosts into `$XDG_STATE_HOME/vev/hosts.json`; that file stores both pinned and learned hosts. See [docs/configuration.md](docs/configuration.md#remote-hosts).
	74	+	SSH bootstraps an authenticated direct UDP connection that resumes after sleep or network changes. Set `VEV_REMOTE_TRANSPORT=stdio` to use SSH only. The remote host needs vev installed; see [remote resilience](docs/remote-resilience.md) for firewall, transport, and host-list details.
109	75
110	76		## Scripting
111	77
112		-	`vev cmd` runs control commands against a running daemon; it never starts one. For example:
	78	+	`vev cmd` controls a running daemon without starting one:
113	79
114	80		```sh
115	81		vev cmd split-right

@@ -117,22 +83,15 @@ vev cmd toast -l warn "build failed"
117	83		vev cmd list-panes --json
118	84		```
119	85
120		-	Target a session explicitly with `-s` (`vev cmd -s work new-tab`). Inside a pane, `--self` targets that pane; it cannot be combined with `-s`. Otherwise vev uses `$VEV` inside a pane, then the only live session; ambiguous targets fail. Run `vev cmd --help` for the scriptable command list and `vev cmd <command> --help` for command usage.
121		-
122		-	Move the focused pane or active tab with these exact forms:
123		-
124		-	```text
125		-	vev cmd [-s <source-session>] [--self] move-pane <destination-session> <destination-tab-id>
126		-	vev cmd [-s <source-session>] [--self] move-tab <destination-session>
127		-	```
128		-
129		-	Use `vev cmd -s <destination-session> list-tabs` to find stable destination tab IDs. Destinations must be live, but may be named or ephemeral; stopped sessions are not eligible. A moved pane is split to the right of the destination tab's focused pane and becomes that tab's internal focus without activating the tab. A moved tab is appended to the destination in the background. If the move empties the source session, its attachment follows the moved pane or tab and activates the destination; existing destination attachments keep their own views.
130		-
131		-	Moving the final tiled pane out of a tab is rejected while that tab has a floating pane slot; close the floating pane or move the whole tab instead. Named-session persistence is best-effort across a move, not crash-atomic across source and destination snapshots.
	86	+	Use `vev cmd --help` for commands and targeting options.
132	87
133		-	## Configuration
	88	+	## Documentation
134	89
135		-	Optional file at `~/.config/vev/config`, reloaded live. Themes, key bindings, palette codes, the floating terminal, status bar scripts: see [docs/configuration.md](docs/configuration.md). Terminal color and VT compatibility notes live in [docs/terminal.md](docs/terminal.md).
	90	+	- [Configuration](docs/configuration.md): bindings, palette, theme, overlays, and bar anchors
	91	+	- [Terminal compatibility](docs/terminal.md)
	92	+	- [Remote resilience](docs/remote-resilience.md)
	93	+	- [Durable session recovery](docs/durable-session-recovery.md)
	94	+	- [Performance](docs/performance.md)
136	95
137	96		## Development
138	97

 ## Install
-Install a pre-built release on Linux x86_64/arm64 or macOS Apple silicon (arm64):
 ```sh
 curl -fsSL https://raw.githubusercontent.com/bnema/vev/main/install.sh | sh
+# Arch Linux: yay -S vev-bin
+# or: go install github.com/bnema/vev@latest
 ```
-On Arch Linux, install [`vev-bin`](https://aur.archlinux.org/packages/vev-bin) from the AUR:
+Releases support Linux x86_64/arm64 and macOS Apple silicon.
-```sh
-yay -S vev-bin
-# or
-paru -S vev-bin
-```
-Alternatively, build and install the binary with Go:
-```sh
-go install github.com/bnema/vev@latest
-```
-The default UI runs entirely from the `vev` binary. The pre-built installer also installs optional external bar anchors, which only take effect when configured in `~/.config/vev/config`.
 ## Usage
 ```text
 vev                              create an ephemeral session
 vev new <name>                   create a named session
-vev attach <name>                attach to a session (alias: a)
+vev attach <name>                attach to a local session (alias: a)
-vev attach user@host[:session]   attach to a remote daemon over SSH
+vev attach user@host[:session]   attach to a remote daemon
-vev ls                           list local sessions
+vev ls [<host>|--all]            list sessions
-vev ls <host>                    list sessions on a known remote host
+vev host add|rm <host>           manage remote hosts
-vev ls --all                     list local and remote sessions
+vev host list                    list remote hosts
-vev host add <host>              add a pinned remote host
+vev kill <name>|--all            kill sessions
-vev host rm <host>               remove a pinned remote host
-vev host list                    list known remote hosts
-vev kill <name>                  kill a session (--all kills everything)
 ```
-The daemon starts on first use and exits with the last session. Ephemeral sessions are numbered, survive detach, and disappear with the daemon. Named sessions persist across daemon restarts and come back with their layout, recovered terminal transcript, and allowlisted processes.
+The daemon starts on first use and exits after the last session. Numbered sessions survive detach; named sessions also survive daemon restarts. See [durable-session recovery](docs/durable-session-recovery.md).
-A session may have multiple attachments. The session owns the PTYs, VT state, tabs, panes, shared PTY content geometry, and ordered mutations. Each attachment owns its window, view, copy mode, overlays, rendering/output state, and reconnect lifecycle, so attachments can focus different tabs or panes without changing one another's view. The latest valid, non-superseded attachment attach, resume, or resize claim controls shared PTY geometry; detaching that attachment falls back to the most recently claimed remaining valid attachment while preserving every attachment's own outer window.
-## Keys
+## Keys and palette
-No prefix key; everything is Alt.
+No prefix key; bindings use Alt.
 | Key | Action |
 |---|---|
 | Alt+Space | command palette |
-| Alt+f | floating terminal for the current tab |
+| Alt+f | floating terminal |
-| Alt+1 .. 9 | switch tab |
+| Alt+1 … 9 | switch tab |
-| Alt+h/j/k/l, Alt+Arrow | focus pane |
+| Alt+h/j/k/l or Alt+Arrow | focus pane |
 | Alt+a | jump to a session needing attention |
-The palette does the rest: type a short code (`SPR` split right, `CNT` new tab, `SSP` session picker, ...) or fuzzy-search the command list. `MFP` (`Move pane to tab`) and `MAT` (`Move tab to session`) open live-destination pickers; the unbound pane consume/expel actions are discoverable there as `MPL` and `MPR`. Named active and stopped sessions are fuzzy-searchable for navigation, and selecting a stopped session resumes it. Scroll up with the mouse to enter scrollback; vim keys move, `v` selects, `y` copies via OSC 52.
+Type a code or fuzzy-search the palette. Common default codes:
-## Remote attach
-```sh
-vev attach user@host[:session]
-```
-The client opens a direct connection to the selected remote daemon. UDP is the default: SSH bootstraps an authenticated UDP endpoint, then the session runs over that connection and resumes after sleep or Wi-Fi changes. vev must be installed on the remote. If your firewall only allows SSH, open the UDP range first (default `61000:61023`, override with `VEV_UDP_PORT_RANGE`):
-```sh
-sudo ufw allow 61000:61023/udp
-```
-Where UDP is not an option, set `VEV_REMOTE_TRANSPORT=stdio` to keep the direct connection inside SSH; this is an explicit transport choice. Every connection has a 15-second handshake deadline, and each command request has a 10-second deadline. Details in [docs/remote-resilience.md](docs/remote-resilience.md).
-List sessions on a known host (OpenSSH resolves aliases from your SSH config):
-```sh
+| Code | Action | Code | Action |
-vev ls arch
+|---|---|---|---|
-vev ls --all
+| `CNT` | new tab | `CNS` | new named session |
-```
+| `SPR` / `SPL` | split right / left | `SPU` / `SPD` | split up / down |
+| `STP` / `TFS` | stack / toggle stack | `TFP` | floating terminal |
+| `MFP` / `MAT` | move pane / tab | `SSP` | session picker |
+| `DET` | detach | `NTC` | notifications |
-Remote session names appear as `session@host`. `vev ls --all` prints local sessions first, then remote sessions in host order. If one host fails, vev still prints the rest and exits non-zero.
+Scroll up to enter copy mode; use vim motions, `v` to select, and `y` to copy. All codes and bindings are configurable in [configuration](docs/configuration.md).
-Manage pinned hosts in the unified host state file through the CLI:
+## Remote attach
 ```sh
-vev host add arch
+vev attach user@host[:session]
-vev host rm arch
-vev host list
 ```
-Successful attaches learn hosts into `$XDG_STATE_HOME/vev/hosts.json`; that file stores both pinned and learned hosts. See [docs/configuration.md](docs/configuration.md#remote-hosts).
+SSH bootstraps an authenticated direct UDP connection that resumes after sleep or network changes. Set `VEV_REMOTE_TRANSPORT=stdio` to use SSH only. The remote host needs vev installed; see [remote resilience](docs/remote-resilience.md) for firewall, transport, and host-list details.
 ## Scripting
-`vev cmd` runs control commands against a running daemon; it never starts one. For example:
+`vev cmd` controls a running daemon without starting one:
 ```sh
 vev cmd split-right
 vev cmd list-panes --json
 ```
-Target a session explicitly with `-s` (`vev cmd -s work new-tab`). Inside a pane, `--self` targets that pane; it cannot be combined with `-s`. Otherwise vev uses `$VEV` inside a pane, then the only live session; ambiguous targets fail. Run `vev cmd --help` for the scriptable command list and `vev cmd <command> --help` for command usage.
+Use `vev cmd --help` for commands and targeting options.
-Move the focused pane or active tab with these exact forms:
-```text
-vev cmd [-s <source-session>] [--self] move-pane <destination-session> <destination-tab-id>
-vev cmd [-s <source-session>] [--self] move-tab <destination-session>
-```
-Use `vev cmd -s <destination-session> list-tabs` to find stable destination tab IDs. Destinations must be live, but may be named or ephemeral; stopped sessions are not eligible. A moved pane is split to the right of the destination tab's focused pane and becomes that tab's internal focus without activating the tab. A moved tab is appended to the destination in the background. If the move empties the source session, its attachment follows the moved pane or tab and activates the destination; existing destination attachments keep their own views.
-Moving the final tiled pane out of a tab is rejected while that tab has a floating pane slot; close the floating pane or move the whole tab instead. Named-session persistence is best-effort across a move, not crash-atomic across source and destination snapshots.
-## Configuration
+## Documentation
-Optional file at `~/.config/vev/config`, reloaded live. Themes, key bindings, palette codes, the floating terminal, status bar scripts: see [docs/configuration.md](docs/configuration.md). Terminal color and VT compatibility notes live in [docs/terminal.md](docs/terminal.md).
+- [Configuration](docs/configuration.md): bindings, palette, theme, overlays, and bar anchors
+- [Terminal compatibility](docs/terminal.md)
+- [Remote resilience](docs/remote-resilience.md)
+- [Durable session recovery](docs/durable-session-recovery.md)
+- [Performance](docs/performance.md)
 ## Development