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- If your outer terminal does not support truecolor, vev converts colors to 256 and shows a one-time warning.
17
18### Install `xterm-direct`
19
20Check on each machine that runs panes, including remote vev hosts:
21
22```sh
23tput -T xterm-direct colors   # expect 16777216
24```
25
26On Arch Linux: `sudo pacman -S ncurses`. On other distributions, install the ncurses terminfo package.
27
28Without root, copy the entry from a machine that has it:
29
30```sh
31infocmp -x xterm-direct > xterm-direct.terminfo   # on the source machine
32tic -x -o ~/.terminfo xterm-direct.terminfo       # on the target machine
33```
34
35Then open a new pane. SSH hosts and containers entered from a pane need the entry too.
36
37## Kitty graphics
38
39Images 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.
40
41Supported:
42
43- `kitten icat` with PNG and JPEG images.
44- Placement, cropping, offsets, z-index, and deletes.
45
46Not supported: file or shared-memory transfer, animations (first frame only), Unicode placeholders, and images in scrollback.
47
48Terminals without Kitty graphics get text only and one warning.
49
50## Kitty keyboard
51
52When 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.
53
54- Detection uses the same short query as Kitty graphics. Other terminals keep their usual keys, and Ctrl+digits reach the pane unchanged.
55- It works with AZERTY and other layouts.
56- Programs in panes that ask for the kitty keyboard protocol (Neovim, Helix, fish) receive it. Others get classic key bytes.
57- Turn it off with `keyboard.kitty-protocol = off` in the [configuration](configuration.md).
58- If vev is killed and your shell gets odd keys, run `printf '\e[<u'` to reset the terminal.
59
60## Environment
61
62- New panes inherit the environment of the client that last attached. Running processes keep theirs.
63- vev always sets `TERM`, `COLORTERM`, `TERM_PROGRAM`, and `VEV`. `SHELL` picks the shell.
64- 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.
65
66## VT features
67
68Each 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.
69
70## Pane size with several clients
71
72When 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.
73
74## Alt+Space
75
76Some terminals send a non-breaking space for Alt+Space. If the palette does not open, rebind `open-palette` in the [configuration](configuration.md).