😽 kitty-scrollback.nvim

Navigate your Kitty scrollback buffer to quickly search, copy, and execute commands in Neovim.

^{(click for video)}

Tip

Expand each section under the Features to see a demo.

Check out Advanced Configuration for more demos!

✨ Features

😻 Navigate Kitty's scrollback buffer with Neovim

Open Kitty's scrollback history (default mapping <C-S-h>)
That's it! You are in Neovim, navigate the scrollback buffer.

🐱 Copy scrollback contents to system clipboard

Open Kitty's scrollback history (default mapping <C-S-h>)
Search backward for a pattern in Neovim ?{pattern}<CR>
Enter Visual mode v and select desired text
Copy selection to clipboard (default mapping <leader>y)
kitty-scrollback.nvim automatically closes

😺 Paste visual selection to Kitty

Open Kitty's scrollback history (default mapping <C-S-h>)
Search backward for a pattern in Neovim ?{pattern}<CR>
Enter Visual mode v and select desired text
Paste visual selection to Kitty (default mapping <S-CR>)
kitty-scrollback.nvim automatically closes and pastes the contents for further editing

🙀 Execute visual selection in Kitty

Open Kitty's scrollback history (default mapping <C-S-h>)
Search backward for a pattern in Neovim ?{pattern}<CR>
Enter Visual mode v and select desired text
Execute visual selection in Kitty (default mapping <C-CR>)
kitty-scrollback.nvim automatically closes and executes the visual selection

😸 Modify and send content from paste window to Kitty

Open Kitty's scrollback history (default mapping <C-S-h>)
Search backward for a pattern in Neovim ?{pattern}<CR>
Enter Visual mode v and select desired text
Copy selection to the paste window in kitty-scrollback.nvim for further edits
- Alternatively, you could just enter Insert mode (i or a) to open an empty floating window (similar to <C-x><C-e> in Bash)
Modify the content in the paste window
Paste the content of the paste window to Kitty (default mapping <S-CR>)
kitty-scrollback.nvim automatically closes and pastes the contents for further editing

😼 Modify and execute content from paste window to Kitty

Open Kitty's scrollback history (default mapping <C-S-h>)
Search backward for a pattern in Neovim ?{pattern}<CR>
Enter Visual mode v and select desired text
Copy selection to the paste window in kitty-scrollback.nvim for further edits
- Alternatively, you could just enter Insert mode (i or a) to open an empty floating window (similar to <C-x><C-e> in Bash)
Modify the content in the paste window
Execute the content of the paste window in Kitty (default mapping <C-CR>)
kitty-scrollback.nvim automatically closes and executes the content of the paste window

🚀 Migrating to v3.0.0

Important

v3.0.0 has breaking changes and requires steps to properly migrate from v2.X.X.

You can ignore this section if you have not previously installed any version of kitty-scrollback.nvim

Migration Steps

Neovim Nerd Font Icon

The Neovim icon is now the default icon in the status window. Update your Nerd Font to the latest version or at least version v3.1.0.

Highlight Groups

Existing highlight groups were renamed. If you were overriding any kitty-scrollback.nvim highlight groups, please update the names referencing the table below.

Previous highlight name	New highlight name
KittyScrollbackNvimNormal	KittyScrollbackNvimStatusWinNormal
KittyScrollbackNvimHeart	KittyScrollbackNvimStatusWinHeartIcon
KittyScrollbackNvimSpinner	KittyScrollbackNvimStatusWinSpinnerIcon
KittyScrollbackNvimReady	KittyScrollbackNvimStatusWinReadyIcon
KittyScrollbackNvimKitty	KittyScrollbackNvimStatusWinKittyIcon
KittyScrollbackNvimVim	KittyScrollbackNvimStatusWinNvimIcon

📚 Prerequisites

Neovim v0.9+
Kitty v0.29+

🏃 Quickstart

To quickly test this plugin without changing your configuration run the command:

sh -c "$(curl -s https://raw.githubusercontent.com/mikesmithgh/kitty-scrollback.nvim/main/scripts/mini.sh)"

Note

It is good practice to first read the script before running sh -c directly from the web

📦 Installation

Using lazy.nvim

  {
    'mikesmithgh/kitty-scrollback.nvim',
    enabled = true,
    lazy = true,
    cmd = { 'KittyScrollbackGenerateKittens', 'KittyScrollbackCheckHealth' },
    event = { 'User KittyScrollbackLaunch' },
    -- version = '*', -- latest stable version, may have breaking changes if major version changed
    -- version = '^3.0.0', -- pin major version, include fixes and features that do not have breaking changes
    config = function()
      require('kitty-scrollback').setup()
    end,
  }

Using packer.nvim

  use({
    'mikesmithgh/kitty-scrollback.nvim',
    disable = false,
    opt = true,
    cmd = { 'KittyScrollbackGenerateKittens', 'KittyScrollbackCheckHealth' },
    event = { 'User KittyScrollbackLaunch' },
    -- tag = '*', -- latest stable version, may have breaking changes if major version changed
    -- tag = 'v3.0.0', -- pin specific tag
    config = function()
      require('kitty-scrollback').setup()
    end,
  })

Using Neovim's built-in package support pack

mkdir -p "$HOME/.local/share/nvim/site/pack/mikesmithgh/start/"
cd $HOME/.local/share/nvim/site/pack/mikesmithgh/start
git clone [email protected]:mikesmithgh/kitty-scrollback.nvim.git
nvim -u NONE -c "helptags kitty-scrollback.nvim/doc" -c q
mkdir -p "$HOME/.config/nvim"
echo "require('kitty-scrollback').setup()" >> "$HOME/.config/nvim/init.lua"

✍️ Configuration

Note

The Advanced Configuration section of the Wiki provides detailed demos of each configuration option.

Kitty

The following steps outline how to properly configure kitty.conf

Enable allow_remote_control

Valid values are yes, socket, socket-only
If kitty-scrollback.nvim is the only application controlling Kitty then socket-only is preferred to continue denying TTY requests.

Set listen_on to a Unix socket

For example, listen_on unix:/tmp/kitty

Enable shell_integration

Set shell_integration to enabled
Do not add the option no-prompt-mark

Add kitty-scrollback.nvim mappings

Generate default Kitten mappings and add to kitty.conf

nvim --headless +'KittyScrollbackGenerateKittens' +'set nonumber' +'set norelativenumber' +'%print' +'quit!' 2>&1

Completely close and reopen Kitty

Check the health of kitty-scrollback.nvim

nvim +'KittyScrollbackCheckHealth'

Follow the instructions of any ERROR or WARNINGS reported during the healthcheck

Test kitty-scrollback.nvim is working as expected by pressing kitty_mod+h to open the scrollback buffer in Neovim

kitty_mod is a special modifier key alias for default shortcuts. You can change the value of this option to alter all default shortcuts that use kitty_mod. See Kitty documentation #opt-kitty.kitty_mod.

The default value of kitty_mod is ctrl+shift. In this example, kitty_mod+h represents ctrl+shift+h.

See example kitty.conf for reference

allow_remote_control yes
listen_on unix:/tmp/kitty
shell_integration enabled

# kitty-scrollback.nvim Kitten alias
action_alias kitty_scrollback_nvim kitten /Users/mike/gitrepos/kitty-scrollback.nvim/python/kitty_scrollback_nvim.py

# Browse scrollback buffer in nvim
map kitty_mod+h kitty_scrollback_nvim
# Browse output of the last shell command in nvim
map kitty_mod+g kitty_scrollback_nvim --config ksb_builtin_last_cmd_output
# Show clicked command output in nvim
mouse_map kitty_mod+right press ungrabbed combine : mouse_select_command_output : kitty_scrollback_nvim --config ksb_builtin_last_visited_cmd_output

Kitten arguments

Arguments that can be passed to the kitty_scrollback_nvim Kitten defined in kitty.conf.

Argument	Description
`--config`	The name of the `kitty-scrollback.nvim` plugin configuration. The configuration can be defined during plugin setup (i.e., `require('kitty-scrollback').setup({ ... })`).
`--no-nvim-args`	Do not provide any arguments to the Neovim instance that displays the scrollback buffer. The default arguments passed to Neovim are `--clean --noplugin -n`. This flag removes those options.
`--nvim-args`	All arguments after this flag are passed to the Neovim instance that displays the scrollback buffer. This must be the last of the `kitty-scrollback.nvim` Kitten arguments that are configured. Otherwise, you may unintentionally send the wrong arguments to Neovim. The default arguments passed to Neovim are `--clean --noplugin -n`. This flag removes those options.
`--env`	Environment variable that is passed to the Neovim instance that displays the scrollback buffer. Format is `--env var_name=var_value`. You may specify multiple config files that will merge all configuration options. Useful for setting `NVIM_APPNAME`
`--cwd`	The current working directory of the Neovim instance that displays the scrollback buffer.