.\" Man page generated from reStructuredText .\" by the Docutils 0.22.3 manpage writer. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "kitten-hints" 1 "Dec 24, 2025" "0.45.0" "kitty" .SH Name kitten-hints \- Select text from screen with keyboard .SH Overview .sp \fIkitty\fP has a \fIhints mode\fP to select and act on arbitrary text snippets currently visible on the screen. For example, you can press \fBctrl+shift+e\fP \%<#\:shortcut-kitty\:.Open-URL> to choose any URL visible on the screen and then open it using your default web browser. .INDENT 0.0 .INDENT 2.5 URL hints mode (images not supported) .UNINDENT .UNINDENT .sp Similarly, you can press \fBctrl+shift+p>f\fP \%<#\:shortcut-kitty\:.Insert-selected-path> 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 \fBgit\fP or \fBls\fP command and adding them to the command line for the next command. .sp You can also press \fBctrl+shift+p>n\fP \%<#\:shortcut-kitty\:.Open-the-selected-file-at-the-selected-line> to select anything that looks like a path or filename followed by a colon and a line number and open the file in your default editor at the specified line number (opening at line number will work only if your editor supports the +linenum command line syntax or is a \(dqknown\(dq editor). The patterns and editor to be used can be modified using options passed to the kitten. For example: .INDENT 0.0 .INDENT 3.5 .sp .EX map ctrl+g kitten hints \-\-type=linenum \-\-linenum\-action=tab nvim +{line} {path} .EE .UNINDENT .UNINDENT .sp will open the selected file in a new tab inside Neovim \% when you press \fBCtrl\fP+\fBG\fP\&. .sp Pressing \fBctrl+shift+p>y\fP \%<#\:shortcut-kitty\:.Open-the-selected-hyperlink> will open hyperlinks \%<#\:term-hyperlinks>, i.e. a URL that has been marked as such by the program running in the terminal, for example, by \fBls \-\-hyperlink=auto\fP\&. If \fBls\fP comes with your OS does not support hyperlink, you may need to install GNU Coreutils \%\&. .sp You can also customize what actions are taken for different types of URLs \%<>\&. .sp \fBNote:\fP .INDENT 0.0 .INDENT 3.5 If there are more hints than letters, hints will use multiple letters. In this case, when you press the first letter, only hints starting with that letter are displayed. Pressing the second letter will select that hint or press \fBEnter\fP or \fBSpace\fP to select the empty hint. .UNINDENT .UNINDENT .sp For mouse lovers, the hints kitten also allows you to click on any matched text to select it instead of typing the hint character. .sp 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 \fBkitty.conf\fP to select various different text snippets. See \fBinsert_selected_path\fP \%<#\:shortcut-kitty\:.Insert-selected-path> for examples. .SH Completely customizing the matching and actions of the kitten .sp 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 \fBcustom\-hints.py\fP in the kitty config directory \%<#\:confloc> with the following contents: .INDENT 0.0 .INDENT 3.5 .sp .EX 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\(aq\ew+\(aq, text)): start, end = m.span() mark_text = text[start:end].replace(\(aq\en\(aq, \(aq\(aq).replace(\(aq\e0\(aq, \(aq\(aq) # The empty dictionary below will be available as groupdicts # in handle_result() and can contain string keys and arbitrary JSON # serializable values. 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[\(aqmatch\(aq], data[\(aqgroupdicts\(aq]): 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\(aqhttps://www.google.com/search?q=define:{word}\(aq) .EE .UNINDENT .UNINDENT .sp Now run kitty with: .INDENT 0.0 .INDENT 3.5 .sp .EX kitty \-o \(aqmap f1 kitten hints \-\-customize\-processing custom\-hints.py\(aq .EE .UNINDENT .UNINDENT .sp When you press the \fBF1\fP key you will be able to select a word to look it up in the Google dictionary. .SH Source code for hints .sp The source code for this kitten is available on GitHub \%\&. .SH Command line interface .INDENT 0.0 .INDENT 3.5 .sp .EX kitten hints [options] .EE .UNINDENT .UNINDENT .sp Select text from the screen using the keyboard. Defaults to searching for URLs. .SS Options .INDENT 0.0 .TP .B \-\-program What program to use to open matched text. Defaults to the default open program for the operating system. Various special values are supported: .INDENT 7.0 .TP .B \fB\-\fP paste the match into the terminal window. .TP .B \fB@\fP copy the match to the clipboard .TP .B \fB*\fP copy the match to the primary selection (on systems that support primary selections) .TP .B \fB@NAME\fP copy the match to the specified buffer, e.g. \fB@a\fP .TP .B \fBdefault\fP run the default open program. Note that when using the hyperlink \fB\-\-type\fP the default is to use the kitty hyperlink handling \%<> facilities. .TP .B \fBlaunch\fP run The launch command \%<> to open the program in a new kitty tab, window, overlay, etc. For example: .INDENT 7.0 .INDENT 3.5 .sp .EX \-\-program \(dqlaunch \-\-type=tab vim\(dq .EE .UNINDENT .UNINDENT .UNINDENT .sp Can be specified multiple times to run multiple programs. .UNINDENT .INDENT 0.0 .TP .B \-\-type The type of text to search for. A value of \fBlinenum\fP is special, it looks for error messages using the pattern specified with \fB\-\-regex\fP, which must have the named groups: \fBpath\fP and \fBline\fP\&. If not specified, will look for \fBpath:line\fP\&. The \fB\-\-linenum\-action\fP option controls where to display the selected error message, other options are ignored. Default: \fBurl\fP Choices: \fBhash\fP, \fBhyperlink\fP, \fBip\fP, \fBline\fP, \fBlinenum\fP, \fBpath\fP, \fBregex\fP, \fBurl\fP, \fBword\fP .UNINDENT .INDENT 0.0 .TP .B \-\-regex The regular expression to use when option \fB\-\-type\fP is set to \fBregex\fP, in Perl 5 syntax. If you specify a numbered group in the regular expression, only the group will be matched. This allows you to match text ignoring a prefix/suffix, as needed. The default expression matches lines. To match text over multiple lines, things get a little tricky, as line endings are a sequence of zero or more null bytes followed by either a carriage return or a newline character. To have a pattern match over line endings you will need to match the character set \fB[\e0\er\en]\fP\&. The newlines and null bytes are automatically stripped from the returned text. If you specify named groups and a \fB\-\-program\fP, then the program will be passed arguments corresponding to each named group of the form \fBkey=value\fP\&. Default: \fB(?m)^\es*(.+?)\es*$\fP .UNINDENT .INDENT 0.0 .TP .B \-\-linenum\-action Where to perform the action on matched errors. \fBself\fP means the current window, \fBwindow\fP a new kitty window, \fBtab\fP a new tab, \fBos_window\fP a new OS window and \fBbackground\fP run in the background. \fBremote\-control\fP is like background but the program can use kitty remote control without needing to turn on remote control globally. The actual action is whatever arguments are provided to the kitten, for example: \fBkitten hints \-\-type=linenum \-\-linenum\-action=tab vim +{line} {path}\fP will open the matched path at the matched line number in vim in a new kitty tab. Note that in order to use \fB\-\-program\fP to copy or paste the provided arguments, you need to use the special value \fBself\fP\&. Default: \fBself\fP Choices: \fBbackground\fP, \fBos_window\fP, \fBremote\-control\fP, \fBself\fP, \fBtab\fP, \fBwindow\fP .UNINDENT .INDENT 0.0 .TP .B \-\-url\-prefixes Comma separated list of recognized URL prefixes. Defaults to the list of prefixes defined by the \fBurl_prefixes\fP \%<#\:opt-kitty\:.url_prefixes> option in \fBkitty.conf\fP\&. Default: \fBdefault\fP .UNINDENT .INDENT 0.0 .TP .B \-\-url\-excluded\-characters Characters to exclude when matching URLs. Defaults to the list of characters defined by the \fBurl_excluded_characters\fP \%<#\:opt-kitty\:.url_excluded_characters> option in \fBkitty.conf\fP\&. The syntax for this option is the same as for \fBurl_excluded_characters\fP \%<#\:opt-kitty\:.url_excluded_characters>\&. Default: \fBdefault\fP .UNINDENT .INDENT 0.0 .TP .B \-\-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 \fBselect_by_word_characters\fP \%<#\:opt-kitty\:.select_by_word_characters> option from \fBkitty.conf\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-minimum\-match\-length The minimum number of characters to consider a match. Default: \fB3\fP .UNINDENT .INDENT 0.0 .TP .B \-\-multiple [=no] Select multiple matches and perform the action on all of them together at the end. In this mode, press \fBEsc\fP to finish selecting. .UNINDENT .INDENT 0.0 .TP .B \-\-multiple\-joiner String for joining multiple selections when copying to the clipboard or inserting into the terminal. The special values are: \fBspace\fP \- a space character, \fBnewline\fP \- a newline, \fBempty\fP \- an empty joiner, \fBjson\fP \- a JSON serialized list, \fBauto\fP \- 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 \fB0\fP for the first selection and \fB\-1\fP for the last. Default: \fBauto\fP .UNINDENT .INDENT 0.0 .TP .B \-\-add\-trailing\-space Add trailing space after matched text. Defaults to \fBauto\fP, which adds the space when used together with \fB\-\-multiple\fP\&. Default: \fBauto\fP Choices: \fBalways\fP, \fBauto\fP, \fBnever\fP .UNINDENT .INDENT 0.0 .TP .B \-\-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: \fB1\fP .UNINDENT .INDENT 0.0 .TP .B \-\-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 you need to specify the \fB\-\-hints\-offset\fP as zero to use the first character to highlight the first match, otherwise it will start with the second character by default. .UNINDENT .INDENT 0.0 .TP .B \-\-ascending [=no] Make the hints increase from top to bottom, instead of decreasing from top to bottom. .UNINDENT .INDENT 0.0 .TP .B \-\-hints\-foreground\-color The foreground color for hints. You can use color names or hex values. For the eight basic named terminal colors you can also use the \fBbright\-\fP prefix to get the bright variant of the color. Default: \fBblack\fP .UNINDENT .INDENT 0.0 .TP .B \-\-hints\-background\-color The background color for hints. You can use color names or hex values. For the eight basic named terminal colors you can also use the \fBbright\-\fP prefix to get the bright variant of the color. Default: \fBgreen\fP .UNINDENT .INDENT 0.0 .TP .B \-\-hints\-text\-color The foreground color for text pointed to by the hints. You can use color names or hex values. For the eight basic named terminal colors you can also use the \fBbright\-\fP prefix to get the bright variant of the color. The default is to pick a suitable color automatically. Default: \fBauto\fP .UNINDENT .INDENT 0.0 .TP .B \-\-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. You can also specify absolute paths to load the script from elsewhere. See \% for details. .UNINDENT .INDENT 0.0 .TP .B \-\-window\-title The title for the hints window, default title is based on the type of text being hinted. .UNINDENT .sp \fBNote:\fP .INDENT 0.0 .INDENT 3.5 To avoid having to specify the same command line options on every invocation, you can use the \fBaction_alias\fP \%<#\:opt-kitty\:.action_alias> option in \fBkitty.conf\fP, creating aliases that have common sets of options. For example: .INDENT 0.0 .INDENT 3.5 .sp .EX action_alias myhints kitten hints \-\-alphabet qfjdkslaureitywovmcxzpq1234567890 map f1 myhints \-\-customize\-processing custom\-hints.py .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SH Author Kovid Goyal .SH Copyright 2025, Kovid Goyal .\" End of generated man page.