Hints¶
kitty has a hints mode to select and act on arbitrary text snippets currently
visible on the screen. For example, you can press ctrl+shift+e
to choose any URL visible on the screen and then open it using your system
browser.

URL hints mode¶
Similarly, you can press ctrl+shift+p>f
to
select anything that looks like a path or filename and then insert it into the
terminal, very useful for picking files from the output of a git
or ls
command and
adding them to the command line for the next command.
You can also press ctrl+shift+p>n
to select anything that looks
like a path or filename followed by a colon and a line number and open
the file in vim at the specified line number. The patterns and editor
to be used can be modified using options passed to the kitten. For example:
map ctrl+g kitten hints --type=linenum --linenum-action=tab nvim +{line} {path}
will open the selected file in a new tab inside neovim when you press ctrl+g.
Pressing ctrl+shift+p>y
will open hyperlinks, i.e. a URL
that has been marked as such by the program running in the terminal,
for example, by ls --hyperlink=auto
. You can also customize what actions are
taken for different types of URLs.
The hints kitten is very powerful to see more detailed help on its various
options and modes of operation, see below. You can use these options to
create mappings in kitty.conf
to select various different text
snippets. See ctrl+shift+p>f
for examples.
Completely customizing the matching and actions of the kitten¶
The hints kitten supports writing simple python scripts that can be used to
completely customize how it finds matches and what happens when a match is
selected. This allows the hints kitten to provide the user interface, while
you can provide the logic for finding matches and performing actions on them.
This is best illustrated with an example. Create the file
custom-hints.py
in the kitty config directory with the following
contents:
import re
def mark(text, args, Mark, extra_cli_args, *a):
# This function is responsible for finding all
# matching text. extra_cli_args are any extra arguments
# passed on the command line when invoking the kitten.
# We mark all individual word for potential selection
for idx, m in enumerate(re.finditer(r'\w+', text)):
start, end = m.span()
mark_text = text[start:end].replace('\n', '').replace('\0', '')
# The empty dictionary below will be available as groupdicts
# in handle_result() and can contain arbitrary data.
yield Mark(idx, start, end, mark_text, {})
def handle_result(args, data, target_window_id, boss, extra_cli_args, *a):
# This function is responsible for performing some
# action on the selected text.
# matches is a list of the selected entries and groupdicts contains
# the arbitrary data associated with each entry in mark() above
matches, groupdicts = [], []
for m, g in zip(data['match'], data['groupdicts']):
if m:
matches.append(m), groupdicts.append(g)
for word, match_data in zip(matches, groupdicts):
# Lookup the word in a dictionary, the open_url function
# will open the provided url in the system browser
boss.open_url(f'https://www.google.com/search?q=define:{word}')
Now run kitty with:
kitty -o 'map f1 kitten hints --customize-processing custom-hints.py'
When you press the F1 key you will be able to select a word to look it up in the Google dictionary.
Command Line Interface¶
kitty +kitten hints [options]
Select text from the screen using the keyboard. Defaults to searching for URLs.
Options¶
-
--program
<PROGRAM>
¶ What program to use to open matched text. Defaults to the default open program for the operating system. Use a value of
-
to paste the match into the terminal window instead. A value of@
will copy the match to the clipboard. A value of*
will copy the match to the primary selection (on systems that support primary selections). A value ofdefault
will run the default open program. Can be specified multiple times to run multiple programs.
-
--type
<TYPE>
¶ The type of text to search for. A value of
linenum
is special, it looks for error messages using the pattern specified with--regex
, which must have the named groups,path
andline
. If not specified, will look forpath:line
. The--linenum-action
option controls where to display the selected error message, other options are ignored. Default:url
Choices:hash, hyperlink, ip, line, linenum, path, regex, url, word
-
--regex
<REGEX>
¶ The regular expression to use when
kitty +kitten hints --type
=regex
. The regular expression is in python syntax. If you specify a numbered group in the regular expression only the group will be matched. This allow you to match text ignoring a prefix/suffix, as needed. The default expression matches lines. To match text over multiple lines you should prefix the regular expression with(?ms)
, which turns on MULTILINE and DOTALL modes for the regex engine. If you specify named groups and akitty +kitten hints --program
then the program will be passed arguments corresponding to each named group of the form key=value. Default:(?m)^\s*(.+)\s*$
-
--linenum-action
<LINENUM_ACTION>
¶ Where to perform the action on matched errors.
self
means the current window,window
a new kitty window,tab
a new tab,os_window
a new OS window andbackground
run in the background. The action to perform on the matched errors. The actual action is whatever arguments are provided to the kitten, for example:kitty + kitten hints --type=linenum --linenum-action=tab vim +{line} {path}
will open the matched path at the matched line number in vim in a new kitty tab. Default:self
Choices:background, os_window, self, tab, window
-
--url-prefixes
<URL_PREFIXES>
¶ Comma separated list of recognized URL prefixes. Defaults, to the list of prefixes defined in kitty.conf. Default:
default
-
--word-characters
<WORD_CHARACTERS>
¶ Characters to consider as part of a word. In addition, all characters marked as alphanumeric in the unicode database will be considered as word characters. Defaults to the select_by_word_characters setting from kitty.conf.
-
--minimum-match-length
<MINIMUM_MATCH_LENGTH>
¶ The minimum number of characters to consider a match. Default:
3
-
--multiple
¶
Select multiple matches and perform the action on all of them together at the end. In this mode, press Esc to finish selecting.
-
--multiple-joiner
<MULTIPLE_JOINER>
¶ String to use to join multiple selections when copying to the clipboard or inserting into the terminal. The special strings: “space”, “newline”, “empty”, “json” and “auto” are interpreted as a space character, a newline an empty joiner, a JSON serialized list and an automatic choice, based on the type of text being selected. In addition, integers are interpreted as zero-based indices into the list of selections. You can use 0 for the first selection and -1 for the last. Default:
auto
-
--add-trailing-space
<ADD_TRAILING_SPACE>
¶ Add trailing space after matched text. Defaults to auto, which adds the space when used together with –multiple. Default:
auto
Choices:always, auto, never
-
--hints-offset
<HINTS_OFFSET>
¶ The offset (from zero) at which to start hint numbering. Note that only numbers greater than or equal to zero are respected. Default:
1
-
--alphabet
<ALPHABET>
¶ The list of characters to use for hints. The default is to use numbers and lowercase English alphabets. Specify your preference as a string of characters. Note that unless you specify the hints offset as zero the first match will be highlighted with the second character you specify.
-
--ascending
¶
Have the hints increase from top to bottom instead of decreasing from top to bottom.
-
--hints-foreground-color
<HINTS_FOREGROUND_COLOR>
¶ The foreground color for hints Default:
black
-
--hints-background-color
<HINTS_BACKGROUND_COLOR>
¶ The background color for hints Default:
green
-
--hints-text-color
<HINTS_TEXT_COLOR>
¶ The foreground color for text pointed to by the hints Default:
gray
-
--customize-processing
<CUSTOMIZE_PROCESSING>
¶ Name of a python file in the kitty config directory which will be imported to provide custom implementations for pattern finding and performing actions on selected matches. See https://sw.kovidgoyal.net/kitty/kittens/hints.html for details. You can also specify absolute paths to load the script from elsewhere.
-
--window-title
<WINDOW_TITLE>
¶ The window title for the hints window, default title is selected based on the type of text being hinted.