Question: <Esc> mappings lost at startup with kitty keyboard protocol.

9 views
Skip to first unread message

Yuki Kitano

unread,
Jan 7, 2026, 4:58:12 PM (5 days ago) Jan 7
to vim...@vim.org
Hello,

I have a question regarding key mappings involving <Esc> when using
Vim with kitty keyboard protocol enabled.

I am not sure whether this is a bug or an expected limitation, so I
would appreciate any clarification.

### Problem
When using Vim with kitty keyboard protocol enabled, mappings
involving `<Esc>` do not work if they are defined during startup.
The same mappings start working after re-sourcing the vimrc.

This does not happen inside tmux or login shell(zsh 5.9).

### Environment
- Vim: 9.1.1975
- Terminal: kitty 0.44.0
- OS: Arch Linux (kernel version 6.17.9) or NixOS 25.11
- TERM: xterm-kitty
- kitty keyboard protocol: enabled
- tmux: works correctly inside tmux

### Steps to reproduce
1. Enable kitty keyboard protocol
2. Start Vim with the following minimal vimrc(`vim --clean -u ~/.vimrc`))
```vim
"~/.vimrc
set hlsearch
nnoremap <Esc><Esc> :nohlsearch<CR>
```
3. Press `<Esc><Esc>` -> mapping does not trigger
4. Run `verbose nnoremap <Esc><Esc>` -> mapping not found.
5. Run `:source $MYVIMRC`
6. Press `<Esc><Esc>` again -> mapping works
7. Run `verbose nnoremap <Esc><Esc>` -> mapping found

### Observations
- At startup, `:verbose nnoremap <Esc><Esc>` reports
'Kitty keyboard protocol: On>
No mapping found'.
- After `:source $MYVIMRC`, the mapping appears and works.
- 'kitten show-key -m kitty` reports `<Esc>` as `CSI 27 ; 1 : 3u`.
- 'kitten show-key -m normal` reports `<Esc>` as `UNIX: ^[ send_text: \x1b`.
- `nnoremap <C-l> :nohlsearch<CR>` mappings work reliably.
- The issue does not occur when running Vim inside `tmux` or login shell.
- Defining the mapping in `~/.vim/after/plugin/keymaps.vim` does not
change the behavior.
- Defining the mapping via `autocmd VimEnter` also does not make it
available at startup.

### Question
- I am not sure whether this is a bug or an expected limitation.
- I am aware that Vim documentation mentions known issues related to
the kitty keyboard protocol (`doc/version9.txt`), but it is unclear
to me whether the behavior described above is an expected consequence
of those limitations or a separate issue.
- I would appreciate any clarification on how mappings involving <Esc>
are expected to behave when kitty keyboard protocol is enabled.

Thank you for your time.
Reply all
Reply to author
Forward
0 new messages