docs(readme): refresh usage and feature overview

commit: 49b5efc3440d8698f26ee76379a181e23d45ae14
author: brice · 3mo ago · 2026-07-04 16:55 UTC
parent: 71edbd4
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

1 file · +71 -22

M README.md +71 -22

@@ -1,9 +1,9 @@
1		-	# vev
	1	+	# vev — Norwegian: web, weave, tissue
2	2
3		-	There is many terminal multiplexers but this one is mine. Written in Go, with no runtime dependencies beyond `golang.org/x/sys` and `golang.org/x/term`. Purely focused on performance, rendering of high output of vertical text, agentic coding and remote work over ssh.
	3	+	There are many terminal multiplexers, but this one is mine. Written in Go, with no runtime dependencies beyond `golang.org/x/sys` and `golang.org/x/term`. Purely focused on performance, rendering high-output vertical text, agentic coding, and remote work over SSH.
4	4
5		-	> [!IMPORTANT]
6		-	> This is totally in alpha
	5	+	> [!IMPORTANT]
	6	+	> This is totally in alpha.
7	7
8	8		## Install
9	9

@@ -11,70 +11,109 @@ There is many terminal multiplexers but this one is mine. Written in Go, with no
11	11		go install github.com/bnema/vev@latest
12	12		```
13	13
14		-	Or from a checkout: `go build -o vev .`
	14	+	From a checkout:
	15	+
	16	+	```sh
	17	+	make install # go install .
	18	+	go build -o vev . # local binary
	19	+	```
15	20
16	21		## Usage
17	22
18		-	```
	23	+	```text
19	24		vev attach to (or create) an ephemeral session
20	25		vev new <name> create and attach to a named session
21	26		vev attach <name> attach to an existing named session (alias: a)
22	27		vev attach user@host[:session] attach to a remote vev daemon over SSH
23		-	vev ls list sessions
	28	+	vev ls list sessions (alias: list)
24	29		vev kill <name> kill a named session
	30	+	vev kill -- <name> kill a name that starts with -
25	31		vev kill --all kill all sessions and stop the daemon
26	32		vev kill --daemon stop the active vev daemon
27		-	vev --help show help
28		-	vev --version show version
	33	+	vev --help show help (aliases: -h, help)
	34	+	vev --version show version (alias: version)
29	35		```
30	36
31		-	Ephemeral sessions get a number (0, 1, 2...) and die when you detach. Named sessions survive detach and live until killed or their last tab closes. The daemon starts on first use and exits when no sessions remain.
	37	+	Ephemeral sessions get a number (`0`, `1`, `2`, ...) and die when you detach. Named sessions survive detach and can be resumed later. The daemon starts on first use and exits when no sessions remain.
	38	+
	39	+	Only one client is attached to a session at a time; attaching again displaces the old client.
32	40
33		-	Remote attach runs `ssh user@host vev _stdio ...` under the hood, so vev must be installed on the remote host and reachable via your normal SSH config. Each remote attach opens one ssh connection. To make reconnects near-instant, enable OpenSSH connection reuse for your hosts in `~/.ssh/config`:
	41	+	## Remote attach
34	42
	43	+	```sh
	44	+	vev attach user@host
	45	+	vev attach user@host:session
35	46		```
	47	+
	48	+	Remote attach runs `ssh user@host vev _stdio ...` under the hood, so `vev` must be installed on the remote host and reachable through your normal SSH config. Omitting `:session` opens an ephemeral remote session.
	49	+
	50	+	For faster reconnects, enable OpenSSH connection reuse:
	51	+
	52	+	```sshconfig
36	53		Host *
37	54		ControlMaster auto
38	55		ControlPath ~/.ssh/cm-%r@%h:%p
39	56		ControlPersist 10m
40	57		```
41	58
42		-	Omitting `:session` opens an ephemeral session on the remote.
43		-
44	59		## Keys
45	60
46		-	All bindings use the Alt modifier directly, no prefix key.
	61	+	All bindings use Alt directly; there is no prefix key.
47	62
48	63		\| Key \| Action \|
49	64		\|---\|---\|
50	65		\| Alt+Space \| open the command palette \|
51	66		\| Alt+1 .. Alt+9 \| switch to tab by number \|
	67	+	\| Alt+h/j/k/l \| focus pane left/down/up/right \|
	68	+	\| Alt+Arrow \| focus pane by direction \|
	69	+	\| Alt+a \| jump to a session with attention \|
52	70
53	71		Some terminals encode Alt+Space as a non-breaking space instead of `ESC Space`; in those terminals, the palette binding depends on whether the terminal can send `ESC Space` for Alt+Space.
54	72
55	73		## Command palette
56	74
57		-	Open the palette with Alt+Space, then type a command code or fuzzy-match its label. Use Up/Down or Ctrl-N/Ctrl-P to move through matches, Enter to run the selected command, and Esc to close the palette.
	75	+	Open the palette with Alt+Space. Type a command code or fuzzy-match the label/description. Use Up/Down or Ctrl-N/Ctrl-P to move, Enter to run, and Esc/Ctrl-C to close.
58	76
59		-	The status bar marks ephemeral sessions with ``, for example `0`. Ephemeral sessions are removed when their client detaches. Renaming an ephemeral session makes it a persistent named session and removes the marker.
	77	+	Successful commands are promoted near the top the next time the palette opens.
60	78
61	79		\| Code \| Action \|
62	80		\|---\|---\|
63	81		\| CNT \| create new tab \|
64	82		\| CNS \| create and switch to a named session \|
65	83		\| CLT \| close current tab \|
66		-	\| NXT \| switch to next tab \|
67		-	\| PVT \| switch to previous tab \|
68		-	\| SSP \| switch session or tab \|
	84	+	\| SPR / SPL / SPU / SPD \| split pane right / left / up / down \|
	85	+	\| STP \| stack a new pane \|
	86	+	\| TST \| toggle focused stack \|
	87	+	\| CLP \| close focused pane \|
	88	+	\| FPL / FPR / FPU / FPD \| focus pane left / right / up / down \|
	89	+	\| NXT / PVT \| switch to next / previous tab \|
	90	+	\| SSP \| open session picker \|
69	91		\| VIS \| enter visual mode \|
70	92		\| RNS \| rename session \|
71	93		\| DET \| detach \|
72	94
73		-	Rename prompts are prefilled with the current session name. Type text, use Backspace to edit, Enter to submit, or Esc/Ctrl-C to cancel. Empty names and names already used by another session are rejected; the prompt stays open and shows the validation error.
	95	+	Rename prompts are prefilled with the current session name. Empty names and names already used by another session are rejected.
74	96
75		-	## Visual mode
	97	+	## Session picker
76	98
77		-	Visual mode freezes a view over history while the program keeps running underneath. Enter it with the `VIS` palette command or by scrolling up with the mouse wheel. The status bar shows `[VISUAL]`; when a line selection is active, selected rows are highlighted, the status bar shows `[SELECT]`, and a visible line cursor marks the active row.
	99	+	Open it with `SSP` in the palette. It lists sessions and tabs, previews the selected target when space allows, and marks stopped sessions.
	100	+
	101	+	\| Key \| Action \|
	102	+	\|---\|---\|
	103	+	\| j / k, Up / Down \| move selection \|
	104	+	\| Enter \| switch to or resume selected target \|
	105	+	\| x \| kill/delete selected target \|
	106	+	\| q, Esc, Ctrl-C \| close picker \|
	107	+
	108	+	## Panes and tabs
	109	+
	110	+	Tabs hold pane layouts. Panes can be split left/right/up/down, stacked, focused by direction, and closed from the command palette. Clicking a pane focuses it.
	111	+
	112	+	The top bar shows numbered tabs. The bottom bar shows the session name; ephemeral sessions are marked with ``, for example `0`.
	113	+
	114	+	## Visual mode and copy
	115	+
	116	+	Visual mode freezes a view over history while the program keeps running underneath. Enter it with the `VIS` palette command or by scrolling up with the mouse wheel.
78	117
79	118		\| Key \| Action \|
80	119		\|---\|---\|

@@ -84,3 +123,13 @@ Visual mode freezes a view over history while the program keeps running undernea
84	123		\| v or Space \| toggle line selection \|
85	124		\| y or Enter \| copy selection and exit \|
86	125		\| q, Esc, Ctrl-C \| exit without copying \|
	126	+
	127	+	Copy uses OSC 52 clipboard sequences when supported by your terminal.
	128	+
	129	+	## Development
	130	+
	131	+	```sh
	132	+	make test # go test ./... -race
	133	+	make lint # goimports check, then go vet ./...
	134	+	make mocks # regenerate mocks
	135	+	```

-# vev
+# vev — Norwegian: web, weave, tissue
-There is many terminal multiplexers but this one is mine. Written in Go, with no runtime dependencies beyond `golang.org/x/sys` and `golang.org/x/term`. Purely focused on performance, rendering of high output of vertical text, agentic coding and remote work over ssh.
+There are many terminal multiplexers, but this one is mine. Written in Go, with no runtime dependencies beyond `golang.org/x/sys` and `golang.org/x/term`. Purely focused on performance, rendering high-output vertical text, agentic coding, and remote work over SSH.
 > [!IMPORTANT]
-> This is totally in alpha
+> This is totally in alpha.
 ## Install
 go install github.com/bnema/vev@latest
 ```
-Or from a checkout: `go build -o vev .`
+From a checkout:
+```sh
+make install        # go install .
+go build -o vev .  # local binary
+```
 ## Usage
-```
+```text
 vev                              attach to (or create) an ephemeral session
 vev new <name>                   create and attach to a named session
 vev attach <name>                attach to an existing named session (alias: a)
 vev attach user@host[:session]   attach to a remote vev daemon over SSH
-vev ls                           list sessions
+vev ls                           list sessions (alias: list)
 vev kill <name>                  kill a named session
+vev kill -- <name>               kill a name that starts with -
 vev kill --all                   kill all sessions and stop the daemon
 vev kill --daemon                stop the active vev daemon
-vev --help                       show help
+vev --help                       show help (aliases: -h, help)
-vev --version                    show version
+vev --version                    show version (alias: version)
 ```
-Ephemeral sessions get a number (0, 1, 2...) and die when you detach. Named sessions survive detach and live until killed or their last tab closes. The daemon starts on first use and exits when no sessions remain.
+Ephemeral sessions get a number (`0`, `1`, `2`, ...) and die when you detach. Named sessions survive detach and can be resumed later. The daemon starts on first use and exits when no sessions remain.
+Only one client is attached to a session at a time; attaching again displaces the old client.
-Remote attach runs `ssh user@host vev _stdio ...` under the hood, so vev must be installed on the remote host and reachable via your normal SSH config. Each remote attach opens one ssh connection. To make reconnects near-instant, enable OpenSSH connection reuse for your hosts in `~/.ssh/config`:
+## Remote attach
+```sh
+vev attach user@host
+vev attach user@host:session
 ```
+Remote attach runs `ssh user@host vev _stdio ...` under the hood, so `vev` must be installed on the remote host and reachable through your normal SSH config. Omitting `:session` opens an ephemeral remote session.
+For faster reconnects, enable OpenSSH connection reuse:
+```sshconfig
 Host *
     ControlMaster auto
     ControlPath ~/.ssh/cm-%r@%h:%p
     ControlPersist 10m
 ```
-Omitting `:session` opens an ephemeral session on the remote.
 ## Keys
-All bindings use the Alt modifier directly, no prefix key.
+All bindings use Alt directly; there is no prefix key.
 | Key | Action |
 |---|---|
 | Alt+Space | open the command palette |
 | Alt+1 .. Alt+9 | switch to tab by number |
+| Alt+h/j/k/l | focus pane left/down/up/right |
+| Alt+Arrow | focus pane by direction |
+| Alt+a | jump to a session with attention |
 Some terminals encode Alt+Space as a non-breaking space instead of `ESC Space`; in those terminals, the palette binding depends on whether the terminal can send `ESC Space` for Alt+Space.
 ## Command palette
-Open the palette with Alt+Space, then type a command code or fuzzy-match its label. Use Up/Down or Ctrl-N/Ctrl-P to move through matches, Enter to run the selected command, and Esc to close the palette.
+Open the palette with Alt+Space. Type a command code or fuzzy-match the label/description. Use Up/Down or Ctrl-N/Ctrl-P to move, Enter to run, and Esc/Ctrl-C to close.
-The status bar marks ephemeral sessions with `*`, for example `0*`. Ephemeral sessions are removed when their client detaches. Renaming an ephemeral session makes it a persistent named session and removes the marker.
+Successful commands are promoted near the top the next time the palette opens.
 | Code | Action |
 |---|---|
 | CNT | create new tab |
 | CNS | create and switch to a named session |
 | CLT | close current tab |
-| NXT | switch to next tab |
+| SPR / SPL / SPU / SPD | split pane right / left / up / down |
-| PVT | switch to previous tab |
+| STP | stack a new pane |
-| SSP | switch session or tab |
+| TST | toggle focused stack |
+| CLP | close focused pane |
+| FPL / FPR / FPU / FPD | focus pane left / right / up / down |
+| NXT / PVT | switch to next / previous tab |
+| SSP | open session picker |
 | VIS | enter visual mode |
 | RNS | rename session |
 | DET | detach |
-Rename prompts are prefilled with the current session name. Type text, use Backspace to edit, Enter to submit, or Esc/Ctrl-C to cancel. Empty names and names already used by another session are rejected; the prompt stays open and shows the validation error.
+Rename prompts are prefilled with the current session name. Empty names and names already used by another session are rejected.
-## Visual mode
+## Session picker
-Visual mode freezes a view over history while the program keeps running underneath. Enter it with the `VIS` palette command or by scrolling up with the mouse wheel. The status bar shows `[VISUAL]`; when a line selection is active, selected rows are highlighted, the status bar shows `[SELECT]`, and a visible line cursor marks the active row.
+Open it with `SSP` in the palette. It lists sessions and tabs, previews the selected target when space allows, and marks stopped sessions.
+| Key | Action |
+|---|---|
+| j / k, Up / Down | move selection |
+| Enter | switch to or resume selected target |
+| x | kill/delete selected target |
+| q, Esc, Ctrl-C | close picker |
+## Panes and tabs
+Tabs hold pane layouts. Panes can be split left/right/up/down, stacked, focused by direction, and closed from the command palette. Clicking a pane focuses it.
+The top bar shows numbered tabs. The bottom bar shows the session name; ephemeral sessions are marked with `*`, for example `0*`.
+## Visual mode and copy
+Visual mode freezes a view over history while the program keeps running underneath. Enter it with the `VIS` palette command or by scrolling up with the mouse wheel.
 | Key | Action |
 |---|---|
 | v or Space | toggle line selection |
 | y or Enter | copy selection and exit |
 | q, Esc, Ctrl-C | exit without copying |
+Copy uses OSC 52 clipboard sequences when supported by your terminal.
+## Development
+```sh
+make test   # go test ./... -race
+make lint   # goimports check, then go vet ./...
+make mocks  # regenerate mocks
+```