1# Terminal support
2
3## Colors
4
5Panes get truecolor when the pane host has the `xterm-direct` terminfo entry.
6
7| Pane host has `xterm-direct`? | `TERM` in panes |
8|---|---|
9| yes | `xterm-direct` |
10| no | `xterm-256color` |
11
12Both set `COLORTERM=truecolor` and `TERM_PROGRAM=vev`.
13
14- vev checks with `infocmp -x xterm-direct` before each new pane (1 second timeout). Existing panes keep their `TERM`.
15- With `xterm-256color`, apps must read `COLORTERM` to use RGB colors.
16
17### Outer terminal color modes
18
19vev picks a color mode for each attachment, so several clients on one session can use different modes. Modes: `truecolor`, `256`, `16`, `monochrome`.
20
21Detection reads the client's `TERM` and `COLORTERM`. The first matching row wins:
22
23| Order | Signal | Mode |
24|---|---|---|
25| 1 | `COLORTERM` is `truecolor` or `24bit`, or `TERM` is `xterm-direct` or ends in `-direct` | truecolor |
26| 2 | `TERM=xterm-kitty` inside kitty | truecolor |
27| 3 | `TERM` is `dumb`, `vt52`, `vt100`, `vt102`, `vt220`, or ends in `-m` or `-mono` | monochrome |
28| 4 | `TERM` contains `256color` | 256 |
29| 5 | `TERM` is `linux`, `ansi`, `cons25`, or ends in `-16color` or `-color` | 16 (8-color terminals use the first 8) |
30| 6 | anything else | 256 (unverified guess) |
31
32When detection finds a terminal with fewer than truecolor colors, vev shows a one-time notice. The notice is not shown for the unverified guess or for a forced mode.
33
34### Override the mode
35
36| Where | Example | Notes |
37|---|---|---|
38| `VEV_COLORS` environment variable | `VEV_COLORS=16 vev` | Wins over the config key. An invalid value is ignored and logged as a warning. |
39| `terminal.colors` in the [configuration](configuration.md) | `terminal.colors = mono` | Applies to every client that has no `VEV_COLORS`. |
40
41Values: `auto`, `truecolor`, `256`, `16`, `mono`. `auto` (or an empty value) means detection. A forced mode never shows the notice.
42
43`VEV_COLORS` and `terminal.colors` are read when the client starts; restart the client to apply a change. A config reload in the running daemon does not change attached clients.
44
45### What each mode changes
46
47Pane content:
48
49| Mode | Pane colors |
50|---|---|
51| truecolor | Unchanged. |
52| 256 | RGB colors map to the xterm 256-color palette. |
53| 16 | RGB and indexed colors 16-255 map to the nearest of the 16 ANSI colors. Underline color is dropped. |
54| monochrome | All colors are dropped. Attributes (bold, underline, reverse, and so on) stay. |
55
56vev's own UI (bars, borders, pickers, overlays):
57
58| Mode | UI |
59|---|---|
60| truecolor, 256 | Full theme. |
61| 16 | No tinted backgrounds. Active and selected items use bold and reverse, secondary text uses faint. The accent is a terminal palette slot. |
62| monochrome | Same as 16 with no color at all. |
63
64The browser terminal and the headless `--ui-driver` always use truecolor, whatever `TERM`, `COLORTERM`, `VEV_COLORS`, or `terminal.colors` say.
65
66### Install `xterm-direct`
67
68Check on each machine that runs panes, including remote vev hosts:
69
70```sh
71tput -T xterm-direct colors   # expect 16777216
72```
73
74On Arch Linux: `sudo pacman -S ncurses`. On other distributions, install the ncurses terminfo package.
75
76Without root, copy the entry from a machine that has it:
77
78```sh
79infocmp -x xterm-direct > xterm-direct.terminfo   # on the source machine
80tic -x -o ~/.terminfo xterm-direct.terminfo       # on the target machine
81```
82
83Then open a new pane. SSH hosts and containers entered from a pane need the entry too.
84
85## Kitty graphics
86
87Images work when your outer terminal supports the Kitty graphics protocol. vev detects this with a short query at attach time; environment variables never enable it.
88
89Supported:
90
91- `kitten icat` with PNG and JPEG images.
92- Placement, cropping, offsets, z-index, and deletes.
93
94Not supported: file or shared-memory transfer, animations (first frame only), Unicode placeholders, and images in scrollback.
95
96Terminals without Kitty graphics get text only and one warning.
97
98## Kitty keyboard
99
100When your outer terminal supports the kitty keyboard protocol (kitty, foot, ghostty, WezTerm, recent Alacritty), vev enables it at startup. Ctrl+1 to Ctrl+9 then switch to the 1st to 9th previous session in the status-bar history. Ctrl+1 goes back to the session you used last.
101
102- Detection uses the same short query as Kitty graphics. Other terminals keep their usual keys, and Ctrl+digits reach the pane unchanged.
103- It works with AZERTY and other layouts.
104- Programs in panes that ask for the kitty keyboard protocol (Neovim, Helix, fish) receive it. Others get classic key bytes.
105- Turn it off with `keyboard.kitty-protocol = off` in the [configuration](configuration.md).
106- If vev is killed and your shell gets odd keys, run `printf '\e[<u'` to reset the terminal.
107
108## Environment
109
110- A session keeps the environment it was created with, including `SHELL`, `PATH`, and `HOME`. A session restored after a daemon restart takes the environment of the first local client that attaches.
111- Desktop and login variables follow the client that last attached:
112  - `WAYLAND_DISPLAY`, `DISPLAY`, `XAUTHORITY`, `XDG_CURRENT_DESKTOP`, and `XDG_SESSION_*` move as one group. A client with a non-empty `WAYLAND_DISPLAY` or `DISPLAY` replaces the whole group, so switching to another compositor or an X11-only desktop drops the old values. A client without a display (console) or connected over SSH leaves the group alone, even with X forwarding: after `ssh -X`, set `DISPLAY` yourself in the panes that need it.
113  - `DBUS_SESSION_BUS_ADDRESS` and `XDG_RUNTIME_DIR` update when the client has them and are never removed. With systemd, all your graphical sessions share them.
114  - `SSH_AUTH_SOCK`, `SSH_AGENT_PID`, `SSH_CONNECTION`, `SSH_CLIENT`, and `SSH_TTY` always match the last client and are removed when it has none.
115- New panes get these values. Running processes keep their own environment; a shell pulls the current values with `vev env <fish|sh>` from its prompt hook:
116
117  ```fish
118  # ~/.config/fish/conf.d/vev.fish
119  if set -q VEV
120      function __vev_env --on-event fish_prompt
121          vev env fish 2>/dev/null | source
122      end
123  end
124  ```
125
126  ```zsh
127  # ~/.zshrc (bash: add the eval to PROMPT_COMMAND)
128  if [[ -n $VEV ]]; then
129    autoload -Uz add-zsh-hook
130    __vev_env() { eval "$(vev env sh 2>/dev/null)" }
131    add-zsh-hook precmd __vev_env
132  fi
133  ```
134
135  The hook overrides values you set by hand in that shell, such as `SSH_AUTH_SOCK` after `eval (ssh-agent)`.
136- `vev cmd env` lists the set variables as `KEY=value` for reading. Scripts should use `vev cmd env --json`, which also lists the variables to unset as `null`.
137- In fish, the hook erases only global variables; a universal variable (`set -U`) with the same name shows through when the session has no value for it.
138- vev always sets `TERM`, `COLORTERM`, `TERM_PROGRAM`, and `VEV`. `SHELL` picks the shell.
139- A remote session opened from the picker uses the remote host's own environment, not yours. This keeps `HOME`, `PATH`, and `SHELL` correct on that host.
140
141## VT features
142
143Each pane has a server-side VT screen with scroll regions, alternate screen, bracketed paste, mouse tracking, synchronized updates, OSC 9/777 notifications, OSC 52 clipboard, and wide (CJK and emoji) characters.
144
145## Pane size with several clients
146
147When several clients attach to one session, pane size follows the client that attached or resized last. Each client keeps its own window, tab, and focus. When that client leaves, the previous one takes over.
148
149## Alt+Space
150
151Some terminals send a non-breaking space for Alt+Space. If the palette does not open, rebind `open-palette` in the [configuration](configuration.md).