chasinglightning
·
2025-06-04
kitty.conf.bak
1# vim:fileencoding=utf-8:foldmethod=marker
2
3# BEGIN_KITTY_THEME
4# Catppuccin-Frappe
5include current-theme.conf
6# END_KITTY_THEME
7
8#: Fonts {{{
9
10#: kitty has very powerful font management. You can configure
11#: individual font faces and even specify special fonts for particular
12#: characters.
13
14font_family Ubuntu Mono
15# bold_font auto
16# italic_font auto
17# bold_italic_font auto
18
19#: You can specify different fonts for the bold/italic/bold-italic
20#: variants. The easiest way to select fonts is to run the `kitten
21#: choose-fonts` command which will present a nice UI for you to
22#: select the fonts you want with previews and support for selecting
23#: variable fonts and font features. If you want to learn to select
24#: fonts manually, read the font specification syntax
25#: <https://sw.kovidgoyal.net/kitty/kittens/choose-fonts/#font-spec-
26#: syntax>.
27
28font_size 16.0
29
30#: Font size (in pts).
31
32# force_ltr no
33
34#: kitty does not support BIDI (bidirectional text), however, for RTL
35#: scripts, words are automatically displayed in RTL. That is to say,
36#: in an RTL script, the words "HELLO WORLD" display in kitty as
37#: "WORLD HELLO", and if you try to select a substring of an RTL-
38#: shaped string, you will get the character that would be there had
39#: the string been LTR. For example, assuming the Hebrew word ירושלים,
40#: selecting the character that on the screen appears to be ם actually
41#: writes into the selection buffer the character י. kitty's default
42#: behavior is useful in conjunction with a filter to reverse the word
43#: order, however, if you wish to manipulate RTL glyphs, it can be
44#: very challenging to work with, so this option is provided to turn
45#: it off. Furthermore, this option can be used with the command line
46#: program GNU FriBidi <https://github.com/fribidi/fribidi#executable>
47#: to get BIDI support, because it will force kitty to always treat
48#: the text as LTR, which FriBidi expects for terminals.
49
50# symbol_map
51
52#: E.g. symbol_map U+E0A0-U+E0A3,U+E0C0-U+E0C7 PowerlineSymbols
53
54#: Map the specified Unicode codepoints to a particular font. Useful
55#: if you need special rendering for some symbols, such as for
56#: Powerline. Avoids the need for patched fonts. Each Unicode code
57#: point is specified in the form `U+<code point in hexadecimal>`. You
58#: can specify multiple code points, separated by commas and ranges
59#: separated by hyphens. This option can be specified multiple times.
60#: The syntax is::
61
62#: symbol_map codepoints Font Family Name
63
64# narrow_symbols
65
66#: E.g. narrow_symbols U+E0A0-U+E0A3,U+E0C0-U+E0C7 1
67
68#: Usually, for Private Use Unicode characters and some symbol/dingbat
69#: characters, if the character is followed by one or more spaces,
70#: kitty will use those extra cells to render the character larger, if
71#: the character in the font has a wide aspect ratio. Using this
72#: option you can force kitty to restrict the specified code points to
73#: render in the specified number of cells (defaulting to one cell).
74#: This option can be specified multiple times. The syntax is::
75
76#: narrow_symbols codepoints [optionally the number of cells]
77
78# disable_ligatures never
79
80#: Choose how you want to handle multi-character ligatures. The
81#: default is to always render them. You can tell kitty to not render
82#: them when the cursor is over them by using cursor to make editing
83#: easier, or have kitty never render them at all by using always, if
84#: you don't like them. The ligature strategy can be set per-window
85#: either using the kitty remote control facility or by defining
86#: shortcuts for it in kitty.conf, for example::
87
88#: map alt+1 disable_ligatures_in active always
89#: map alt+2 disable_ligatures_in all never
90#: map alt+3 disable_ligatures_in tab cursor
91
92#: Note that this refers to programming ligatures, typically
93#: implemented using the calt OpenType feature. For disabling general
94#: ligatures, use the font_features option.
95
96# font_features
97
98#: E.g. font_features none
99
100#: Choose exactly which OpenType features to enable or disable. Note
101#: that for the main fonts, features can be specified when selecting
102#: the font using the choose-fonts kitten. This setting is useful for
103#: fallback fonts.
104
105#: Some fonts might have features worthwhile in a terminal. For
106#: example, Fira Code includes a discretionary feature, zero, which in
107#: that font changes the appearance of the zero (0), to make it more
108#: easily distinguishable from Ø. Fira Code also includes other
109#: discretionary features known as Stylistic Sets which have the tags
110#: ss01 through ss20.
111
112#: For the exact syntax to use for individual features, see the
113#: HarfBuzz documentation <https://harfbuzz.github.io/harfbuzz-hb-
114#: common.html#hb-feature-from-string>.
115
116#: Note that this code is indexed by PostScript name, and not the font
117#: family. This allows you to define very precise feature settings;
118#: e.g. you can disable a feature in the italic font but not in the
119#: regular font.
120
121#: On Linux, font features are first read from the FontConfig database
122#: and then this option is applied, so they can be configured in a
123#: single, central place.
124
125#: To get the PostScript name for a font, use the `fc-scan file.ttf`
126#: command on Linux or the `Font Book tool on macOS
127#: <https://apple.stackexchange.com/questions/79875/how-can-i-get-the-
128#: postscript-name-of-a-ttf-font-installed-in-os-x>`__.
129
130#: Enable alternate zero and oldstyle numerals::
131
132#: font_features FiraCode-Retina +zero +onum
133
134#: Enable only alternate zero in the bold font::
135
136#: font_features FiraCode-Bold +zero
137
138#: Disable the normal ligatures, but keep the calt feature which (in
139#: this font) breaks up monotony::
140
141#: font_features TT2020StyleB-Regular -liga +calt
142
143#: In conjunction with force_ltr, you may want to disable Arabic
144#: shaping entirely, and only look at their isolated forms if they
145#: show up in a document. You can do this with e.g.::
146
147#: font_features UnifontMedium +isol -medi -fina -init
148
149# modify_font
150
151#: Modify font characteristics such as the position or thickness of
152#: the underline and strikethrough. The modifications can have the
153#: suffix px for pixels or % for percentage of original value. No
154#: suffix means use pts. For example::
155
156#: modify_font underline_position -2
157#: modify_font underline_thickness 150%
158#: modify_font strikethrough_position 2px
159
160#: Additionally, you can modify the size of the cell in which each
161#: font glyph is rendered and the baseline at which the glyph is
162#: placed in the cell. For example::
163
164#: modify_font cell_width 80%
165#: modify_font cell_height -2px
166#: modify_font baseline 3
167
168#: Note that modifying the baseline will automatically adjust the
169#: underline and strikethrough positions by the same amount.
170#: Increasing the baseline raises glyphs inside the cell and
171#: decreasing it lowers them. Decreasing the cell size might cause
172#: rendering artifacts, so use with care.
173
174# box_drawing_scale 0.001, 1, 1.5, 2
175
176#: The sizes of the lines used for the box drawing Unicode characters.
177#: These values are in pts. They will be scaled by the monitor DPI to
178#: arrive at a pixel value. There must be four values corresponding to
179#: thin, normal, thick, and very thick lines.
180
181# undercurl_style thin-sparse
182
183#: The style with which undercurls are rendered. This option takes the
184#: form (thin|thick)-(sparse|dense). Thin and thick control the
185#: thickness of the undercurl. Sparse and dense control how often the
186#: curl oscillates. With sparse the curl will peak once per character,
187#: with dense twice. Changing this option dynamically via reloading
188#: the config or remote control is undefined.
189
190# underline_exclusion 1
191
192#: By default kitty renders gaps in underlines when they overlap with
193#: descenders (the parts of letters below the baseline, such as for y,
194#: q, p etc.). This option controls the thickness of the gaps. It can
195#: be either a unitless number in which case it is a fraction of the
196#: underline thickness as specified in the font or it can have a
197#: suffix of px for pixels or pt for points. Set to zero to disable
198#: the gaps. Changing this option dynamically via reloading the config
199#: or remote control is undefined.
200
201# text_composition_strategy platform
202
203#: Control how kitty composites text glyphs onto the background color.
204#: The default value of platform tries for text rendering as close to
205#: "native" for the platform kitty is running on as possible.
206
207#: A value of legacy uses the old (pre kitty 0.28) strategy for how
208#: glyphs are composited. This will make dark text on light
209#: backgrounds look thicker and light text on dark backgrounds
210#: thinner. It might also make some text appear like the strokes are
211#: uneven.
212
213#: You can fine tune the actual contrast curve used for glyph
214#: composition by specifying up to two space-separated numbers for
215#: this setting.
216
217#: The first number is the gamma adjustment, which controls the
218#: thickness of dark text on light backgrounds. Increasing the value
219#: will make text appear thicker. The default value for this is 1.0 on
220#: Linux and 1.7 on macOS. Valid values are 0.01 and above. The result
221#: is scaled based on the luminance difference between the background
222#: and the foreground. Dark text on light backgrounds receives the
223#: full impact of the curve while light text on dark backgrounds is
224#: affected very little.
225
226#: The second number is an additional multiplicative contrast. It is
227#: percentage ranging from 0 to 100. The default value is 0 on Linux
228#: and 30 on macOS.
229
230#: If you wish to achieve similar looking thickness in light and dark
231#: themes, a good way to experiment is start by setting the value to
232#: 1.0 0 and use a dark theme. Then adjust the second parameter until
233#: it looks good. Then switch to a light theme and adjust the first
234#: parameter until the perceived thickness matches the dark theme.
235
236# text_fg_override_threshold 0
237
238#: A setting to prevent low contrast between foreground and background
239#: colors. Useful when working with applications that use colors that
240#: do not contrast well with your preferred color scheme. The default
241#: value is 0, which means no color overriding is performed. There are
242#: two modes of operation:
243
244#: A value with the suffix ratio represents the minimum accepted
245#: contrast ratio between the foreground and background color.
246#: Possible values range from 0.0 ratio to 21.0 ratio. For example, to
247#: meet WCAG level AA
248#: <https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines>
249#: a value of 4.5 ratio can be provided. The algorithm is implemented
250#: using HSLuv <https://www.hsluv.org/> which enables it to change the
251#: perceived lightness of a color just as much as needed without
252#: really changing its hue and saturation.
253
254#: A value with the suffix % represents the minimum accepted
255#: difference in luminance between the foreground and background
256#: color, below which kitty will override the foreground color. It is
257#: percentage ranging from 0 % to 100 %. If the difference in
258#: luminance of the foreground and background is below this threshold,
259#: the foreground color will be set to white if the background is dark
260#: or black if the background is light.
261
262#: WARNING: Some programs use characters (such as block characters)
263#: for graphics display and may expect to be able to set the
264#: foreground and background to the same color (or similar colors). If
265#: you see unexpected stripes, dots, lines, incorrect color, no color
266#: where you expect color, or any kind of graphic display problem try
267#: setting text_fg_override_threshold to 0 to see if this is the cause
268#: of the problem or consider using the ratio mode of operation
269#: described above instead of the % mode of operation.
270
271#: }}}
272
273#: Text cursor customization {{{
274
275# cursor #cccccc
276
277#: Default text cursor color. If set to the special value none the
278#: cursor will be rendered with a "reverse video" effect. Its color
279#: will be the color of the text in the cell it is over and the text
280#: will be rendered with the background color of the cell. Note that
281#: if the program running in the terminal sets a cursor color, this
282#: takes precedence. Also, the cursor colors are modified if the cell
283#: background and foreground colors have very low contrast. Note that
284#: some themes set this value, so if you want to override it, place
285#: your value after the lines where the theme file is included.
286
287# cursor_text_color #111111
288
289#: The color of text under the cursor. If you want it rendered with
290#: the background color of the cell underneath instead, use the
291#: special keyword: `background`. Note that if cursor is set to none
292#: then this option is ignored. Note that some themes set this value,
293#: so if you want to override it, place your value after the lines
294#: where the theme file is included.
295
296# cursor_shape block
297
298#: The cursor shape can be one of block, beam, underline. Note that
299#: when reloading the config this will be changed only if the cursor
300#: shape has not been set by the program running in the terminal. This
301#: sets the default cursor shape, applications running in the terminal
302#: can override it. In particular, shell integration
303#: <https://sw.kovidgoyal.net/kitty/shell-integration/> in kitty sets
304#: the cursor shape to beam at shell prompts. You can avoid this by
305#: setting shell_integration to no-cursor.
306
307# cursor_shape_unfocused hollow
308
309#: Defines the text cursor shape when the OS window is not focused.
310#: The unfocused cursor shape can be one of block, beam, underline,
311#: hollow and unchanged (leave the cursor shape as it is).
312
313# cursor_beam_thickness 1.5
314
315#: The thickness of the beam cursor (in pts).
316
317# cursor_underline_thickness 2.0
318
319#: The thickness of the underline cursor (in pts).
320
321# cursor_blink_interval -1
322
323#: The interval to blink the cursor (in seconds). Set to zero to
324#: disable blinking. Negative values mean use system default. Note
325#: that the minimum interval will be limited to repaint_delay. You can
326#: also animate the cursor blink by specifying an easing function. For
327#: example, setting this to option to 0.5 ease-in-out will cause the
328#: cursor blink to be animated over a second, in the first half of the
329#: second it will go from opaque to transparent and then back again
330#: over the next half. You can specify different easing functions for
331#: the two halves, for example: -1 linear ease-out. kitty supports all
332#: the CSS easing functions <https://developer.mozilla.org/en-
333#: US/docs/Web/CSS/easing-function>. Note that turning on animations
334#: uses extra power as it means the screen is redrawn multiple times
335#: per blink interval. See also, cursor_stop_blinking_after.
336
337# cursor_stop_blinking_after 15.0
338
339#: Stop blinking cursor after the specified number of seconds of
340#: keyboard inactivity. Set to zero to never stop blinking.
341
342# cursor_trail 0
343
344#: Set this to a value larger than zero to enable a "cursor trail"
345#: animation. This is an animation that shows a "trail" following the
346#: movement of the text cursor. It makes it easy to follow large
347#: cursor jumps and makes for a cool visual effect of the cursor
348#: zooming around the screen. The actual value of this option controls
349#: when the animation is triggered. It is a number of milliseconds.
350#: The trail animation only follows cursors that have stayed in their
351#: position for longer than the specified number of milliseconds. This
352#: prevents trails from appearing for cursors that rapidly change
353#: their positions during UI updates in complex applications. See
354#: cursor_trail_decay to control the animation speed and
355#: cursor_trail_start_threshold to control when a cursor trail is
356#: started.
357
358# cursor_trail_decay 0.1 0.4
359
360#: Controls the decay times for the cursor trail effect when the
361#: cursor_trail is enabled. This option accepts two positive float
362#: values specifying the fastest and slowest decay times in seconds.
363#: The first value corresponds to the fastest decay time (minimum),
364#: and the second value corresponds to the slowest decay time
365#: (maximum). The second value must be equal to or greater than the
366#: first value. Smaller values result in a faster decay of the cursor
367#: trail. Adjust these values to control how quickly the cursor trail
368#: fades away.
369
370# cursor_trail_start_threshold 2
371
372#: Set the distance threshold for starting the cursor trail. This
373#: option accepts a positive integer value that represents the minimum
374#: number of cells the cursor must move before the trail is started.
375#: When the cursor moves less than this threshold, the trail is
376#: skipped, reducing unnecessary cursor trail animation.
377
378#: }}}
379
380#: Scrollback {{{
381
382# scrollback_lines 2000
383
384#: Number of lines of history to keep in memory for scrolling back.
385#: Memory is allocated on demand. Negative numbers are (effectively)
386#: infinite scrollback. Note that using very large scrollback is not
387#: recommended as it can slow down performance of the terminal and
388#: also use large amounts of RAM. Instead, consider using
389#: scrollback_pager_history_size. Note that on config reload if this
390#: is changed it will only affect newly created windows, not existing
391#: ones.
392
393# scrollback_indicator_opacity 1.0
394
395#: The opacity of the scrollback indicator which is a small colored
396#: rectangle that moves along the right hand side of the window as you
397#: scroll, indicating what fraction you have scrolled. The default is
398#: one which means fully opaque, aka visible. Set to a value between
399#: zero and one to make the indicator less visible.
400
401# scrollback_pager less --chop-long-lines --RAW-CONTROL-CHARS +INPUT_LINE_NUMBER
402
403#: Program with which to view scrollback in a new window. The
404#: scrollback buffer is passed as STDIN to this program. If you change
405#: it, make sure the program you use can handle ANSI escape sequences
406#: for colors and text formatting. INPUT_LINE_NUMBER in the command
407#: line above will be replaced by an integer representing which line
408#: should be at the top of the screen. Similarly CURSOR_LINE and
409#: CURSOR_COLUMN will be replaced by the current cursor position or
410#: set to 0 if there is no cursor, for example, when showing the last
411#: command output.
412
413# scrollback_pager_history_size 0
414
415#: Separate scrollback history size (in MB), used only for browsing
416#: the scrollback buffer with pager. This separate buffer is not
417#: available for interactive scrolling but will be piped to the pager
418#: program when viewing scrollback buffer in a separate window. The
419#: current implementation stores the data in UTF-8, so approximately
420#: 10000 lines per megabyte at 100 chars per line, for pure ASCII,
421#: unformatted text. A value of zero or less disables this feature.
422#: The maximum allowed size is 4GB. Note that on config reload if this
423#: is changed it will only affect newly created windows, not existing
424#: ones.
425
426# scrollback_fill_enlarged_window no
427
428#: Fill new space with lines from the scrollback buffer after
429#: enlarging a window.
430
431# wheel_scroll_multiplier 5.0
432
433#: Multiplier for the number of lines scrolled by the mouse wheel.
434#: Note that this is only used for low precision scrolling devices,
435#: not for high precision scrolling devices on platforms such as macOS
436#: and Wayland. Use negative numbers to change scroll direction. See
437#: also wheel_scroll_min_lines.
438
439# wheel_scroll_min_lines 1
440
441#: The minimum number of lines scrolled by the mouse wheel. The scroll
442#: multiplier wheel_scroll_multiplier only takes effect after it
443#: reaches this number. Note that this is only used for low precision
444#: scrolling devices like wheel mice that scroll by very small amounts
445#: when using the wheel. With a negative number, the minimum number of
446#: lines will always be added.
447
448# touch_scroll_multiplier 1.0
449
450#: Multiplier for the number of lines scrolled by a touchpad. Note
451#: that this is only used for high precision scrolling devices on
452#: platforms such as macOS and Wayland. Use negative numbers to change
453#: scroll direction.
454
455#: }}}
456
457#: Mouse {{{
458
459# mouse_hide_wait 3.0
460
461#: Hide mouse cursor after the specified number of seconds of the
462#: mouse not being used. Set to zero to disable mouse cursor hiding.
463#: Set to a negative value to hide the mouse cursor immediately when
464#: typing text. Disabled by default on macOS as getting it to work
465#: robustly with the ever-changing sea of bugs that is Cocoa is too
466#: much effort.
467
468# url_color #0087bd
469# url_style curly
470
471#: The color and style for highlighting URLs on mouse-over. url_style
472#: can be one of: none, straight, double, curly, dotted, dashed.
473
474# open_url_with default
475
476#: The program to open clicked URLs. The special value default will
477#: first look for any URL handlers defined via the open_actions
478#: <https://sw.kovidgoyal.net/kitty/open_actions/> facility and if non
479#: are found, it will use the Operating System's default URL handler
480#: (open on macOS and xdg-open on Linux).
481
482# url_prefixes file ftp ftps gemini git gopher http https irc ircs kitty mailto news sftp ssh
483
484#: The set of URL prefixes to look for when detecting a URL under the
485#: mouse cursor.
486
487# detect_urls yes
488
489#: Detect URLs under the mouse. Detected URLs are highlighted with an
490#: underline and the mouse cursor becomes a hand over them. Even if
491#: this option is disabled, URLs are still clickable. See also the
492#: underline_hyperlinks option to control how hyperlinks (as opposed
493#: to plain text URLs) are displayed.
494
495# url_excluded_characters
496
497#: Additional characters to be disallowed from URLs, when detecting
498#: URLs under the mouse cursor. By default, all characters that are
499#: legal in URLs are allowed. Additionally, newlines are allowed (but
500#: stripped). This is to accommodate programs such as mutt that add
501#: hard line breaks even for continued lines. \n can be added to this
502#: option to disable this behavior. Special characters can be
503#: specified using backslash escapes, to specify a backslash use a
504#: double backslash.
505
506# show_hyperlink_targets no
507
508#: When the mouse hovers over a terminal hyperlink, show the actual
509#: URL that will be activated when the hyperlink is clicked.
510
511# underline_hyperlinks hover
512
513#: Control how hyperlinks are underlined. They can either be
514#: underlined on mouse hover, always (i.e. permanently underlined) or
515#: never which means that kitty will not apply any underline styling
516#: to hyperlinks. Note that the value of always only applies to real
517#: (OSC 8) hyperlinks not text that is detected to be a URL on mouse
518#: hover. Uses the url_style and url_color settings for the underline
519#: style. Note that reloading the config and changing this value
520#: to/from always will only affect text subsequently received by
521#: kitty.
522
523# copy_on_select no
524
525#: Copy to clipboard or a private buffer on select. With this set to
526#: clipboard, selecting text with the mouse will cause the text to be
527#: copied to clipboard. Useful on platforms such as macOS that do not
528#: have the concept of primary selection. You can instead specify a
529#: name such as a1 to copy to a private kitty buffer. Map a shortcut
530#: with the paste_from_buffer action to paste from this private
531#: buffer. For example::
532
533#: copy_on_select a1
534#: map shift+cmd+v paste_from_buffer a1
535
536#: Note that copying to the clipboard is a security risk, as all
537#: programs, including websites open in your browser can read the
538#: contents of the system clipboard.
539
540# clear_selection_on_clipboard_loss no
541
542#: When the contents of the clipboard no longer reflect the current
543#: selection, clear it. This is primarily useful on platforms such as
544#: Linux where selecting text automatically copies it to a special
545#: "primary selection" clipboard or if you have copy_on_select set to
546#: clipboard.
547
548#: Note that on macOS the system does not provide notifications when
549#: the clipboard owner is changed, so there, copying to clipboard in a
550#: non-kitty application will not clear selections even if
551#: copy_on_select is enabled.
552
553# paste_actions quote-urls-at-prompt,confirm
554
555#: A comma separated list of actions to take when pasting text into
556#: the terminal. The supported paste actions are:
557
558#: quote-urls-at-prompt:
559#: If the text being pasted is a URL and the cursor is at a shell prompt,
560#: automatically quote the URL (needs shell_integration).
561#: replace-dangerous-control-codes
562#: Replace dangerous control codes from pasted text, without confirmation.
563#: replace-newline
564#: Replace the newline character from pasted text, without confirmation.
565#: confirm:
566#: Confirm the paste if the text to be pasted contains any terminal control codes
567#: as this can be dangerous, leading to code execution if the shell/program running
568#: in the terminal does not properly handle these.
569#: confirm-if-large
570#: Confirm the paste if it is very large (larger than 16KB) as pasting
571#: large amounts of text into shells can be very slow.
572#: filter:
573#: Run the filter_paste() function from the file paste-actions.py in
574#: the kitty config directory on the pasted text. The text returned by the
575#: function will be actually pasted.
576#: no-op:
577#: Has no effect.
578
579# strip_trailing_spaces never
580
581#: Remove spaces at the end of lines when copying to clipboard. A
582#: value of smart will do it when using normal selections, but not
583#: rectangle selections. A value of always will always do it.
584
585# select_by_word_characters @-./_~?&=%+#
586
587#: Characters considered part of a word when double clicking. In
588#: addition to these characters any character that is marked as an
589#: alphanumeric character in the Unicode database will be matched.
590
591# select_by_word_characters_forward
592
593#: Characters considered part of a word when extending the selection
594#: forward on double clicking. In addition to these characters any
595#: character that is marked as an alphanumeric character in the
596#: Unicode database will be matched.
597
598#: If empty (default) select_by_word_characters will be used for both
599#: directions.
600
601# click_interval -1.0
602
603#: The interval between successive clicks to detect double/triple
604#: clicks (in seconds). Negative numbers will use the system default
605#: instead, if available, or fallback to 0.5.
606
607# focus_follows_mouse no
608
609#: Set the active window to the window under the mouse when moving the
610#: mouse around. On macOS, this will also cause the OS Window under
611#: the mouse to be focused automatically when the mouse enters it.
612
613# pointer_shape_when_grabbed arrow
614
615#: The shape of the mouse pointer when the program running in the
616#: terminal grabs the mouse.
617
618# default_pointer_shape beam
619
620#: The default shape of the mouse pointer.
621
622# pointer_shape_when_dragging beam crosshair
623
624#: The default shape of the mouse pointer when dragging across text.
625#: The optional second value sets the shape when dragging in
626#: rectangular selection mode.
627
628#: Mouse actions {{{
629
630#: Mouse buttons can be mapped to perform arbitrary actions. The
631#: syntax is:
632
633#: .. code-block:: none
634
635#: mouse_map button-name event-type modes action
636
637#: Where button-name is one of left, middle, right, b1 ... b8 with
638#: added keyboard modifiers. For example: ctrl+shift+left refers to
639#: holding the Ctrl+Shift keys while clicking with the left mouse
640#: button. The value b1 ... b8 can be used to refer to up to eight
641#: buttons on a mouse.
642
643#: event-type is one of press, release, doublepress, triplepress,
644#: click, doubleclick. modes indicates whether the action is performed
645#: when the mouse is grabbed by the program running in the terminal,
646#: or not. The values are grabbed or ungrabbed or a comma separated
647#: combination of them. grabbed refers to when the program running in
648#: the terminal has requested mouse events. Note that the click and
649#: double click events have a delay of click_interval to disambiguate
650#: from double and triple presses.
651
652#: You can run kitty with the kitty --debug-input command line option
653#: to see mouse events. See the builtin actions below to get a sense
654#: of what is possible.
655
656#: If you want to unmap a button, map it to nothing. For example, to
657#: disable opening of URLs with a plain click::
658
659#: mouse_map left click ungrabbed
660
661#: See all the mappable actions including mouse actions here
662#: <https://sw.kovidgoyal.net/kitty/actions/>.
663
664#: .. note::
665#: Once a selection is started, releasing the button that started it will
666#: automatically end it and no release event will be dispatched.
667
668# clear_all_mouse_actions no
669
670#: Remove all mouse action definitions up to this point. Useful, for
671#: instance, to remove the default mouse actions.
672
673#: Click the link under the mouse or move the cursor
674
675# mouse_map left click ungrabbed mouse_handle_click selection link prompt
676
677#:: First check for a selection and if one exists do nothing. Then
678#:: check for a link under the mouse cursor and if one exists, click
679#:: it. Finally check if the click happened at the current shell
680#:: prompt and if so, move the cursor to the click location. Note
681#:: that this requires shell integration
682#:: <https://sw.kovidgoyal.net/kitty/shell-integration/> to work.
683
684#: Click the link under the mouse or move the cursor even when grabbed
685
686# mouse_map shift+left click grabbed,ungrabbed mouse_handle_click selection link prompt
687
688#:: Same as above, except that the action is performed even when the
689#:: mouse is grabbed by the program running in the terminal.
690
691#: Click the link under the mouse cursor
692
693# mouse_map ctrl+shift+left release grabbed,ungrabbed mouse_handle_click link
694
695#:: Variant with Ctrl+Shift is present because the simple click based
696#:: version has an unavoidable delay of click_interval, to
697#:: disambiguate clicks from double clicks.
698
699#: Discard press event for link click
700
701# mouse_map ctrl+shift+left press grabbed discard_event
702
703#:: Prevent this press event from being sent to the program that has
704#:: grabbed the mouse, as the corresponding release event is used to
705#:: open a URL.
706
707#: Paste from the primary selection
708
709# mouse_map middle release ungrabbed paste_from_selection
710
711#: Start selecting text
712
713# mouse_map left press ungrabbed mouse_selection normal
714
715#: Start selecting text in a rectangle
716
717# mouse_map ctrl+alt+left press ungrabbed mouse_selection rectangle
718
719#: Select a word
720
721# mouse_map left doublepress ungrabbed mouse_selection word
722
723#: Select a line
724
725# mouse_map left triplepress ungrabbed mouse_selection line
726
727#: Select line from point
728
729# mouse_map ctrl+alt+left triplepress ungrabbed mouse_selection line_from_point
730
731#:: Select from the clicked point to the end of the line. If you
732#:: would like to select the word at the point and then extend to the
733#:: rest of the line, change `line_from_point` to
734#:: `word_and_line_from_point`.
735
736#: Extend the current selection
737
738# mouse_map right press ungrabbed mouse_selection extend
739
740#:: If you want only the end of the selection to be moved instead of
741#:: the nearest boundary, use move-end instead of extend.
742
743#: Paste from the primary selection even when grabbed
744
745# mouse_map shift+middle release ungrabbed,grabbed paste_selection
746# mouse_map shift+middle press grabbed discard_event
747
748#: Start selecting text even when grabbed
749
750# mouse_map shift+left press ungrabbed,grabbed mouse_selection normal
751
752#: Start selecting text in a rectangle even when grabbed
753
754# mouse_map ctrl+shift+alt+left press ungrabbed,grabbed mouse_selection rectangle
755
756#: Select a word even when grabbed
757
758# mouse_map shift+left doublepress ungrabbed,grabbed mouse_selection word
759
760#: Select a line even when grabbed
761
762# mouse_map shift+left triplepress ungrabbed,grabbed mouse_selection line
763
764#: Select line from point even when grabbed
765
766# mouse_map ctrl+shift+alt+left triplepress ungrabbed,grabbed mouse_selection line_from_point
767
768#:: Select from the clicked point to the end of the line even when
769#:: grabbed. If you would like to select the word at the point and
770#:: then extend to the rest of the line, change `line_from_point` to
771#:: `word_and_line_from_point`.
772
773#: Extend the current selection even when grabbed
774
775# mouse_map shift+right press ungrabbed,grabbed mouse_selection extend
776
777#: Show clicked command output in pager
778
779# mouse_map ctrl+shift+right press ungrabbed mouse_show_command_output
780
781#:: Requires shell integration
782#:: <https://sw.kovidgoyal.net/kitty/shell-integration/> to work.
783
784#: }}}
785
786#: }}}
787
788#: Performance tuning {{{
789
790# repaint_delay 10
791
792#: Delay between screen updates (in milliseconds). Decreasing it,
793#: increases frames-per-second (FPS) at the cost of more CPU usage.
794#: The default value yields ~100 FPS which is more than sufficient for
795#: most uses. Note that to actually achieve 100 FPS, you have to
796#: either set sync_to_monitor to no or use a monitor with a high
797#: refresh rate. Also, to minimize latency when there is pending input
798#: to be processed, this option is ignored.
799
800# input_delay 3
801
802#: Delay before input from the program running in the terminal is
803#: processed (in milliseconds). Note that decreasing it will increase
804#: responsiveness, but also increase CPU usage and might cause flicker
805#: in full screen programs that redraw the entire screen on each loop,
806#: because kitty is so fast that partial screen updates will be drawn.
807#: This setting is ignored when the input buffer is almost full.
808
809# sync_to_monitor yes
810
811#: Sync screen updates to the refresh rate of the monitor. This
812#: prevents screen tearing
813#: <https://en.wikipedia.org/wiki/Screen_tearing> when scrolling.
814#: However, it limits the rendering speed to the refresh rate of your
815#: monitor. With a very high speed mouse/high keyboard repeat rate,
816#: you may notice some slight input latency. If so, set this to no.
817
818#: }}}
819
820#: Terminal bell {{{
821
822# enable_audio_bell yes
823
824#: The audio bell. Useful to disable it in environments that require
825#: silence.
826
827# visual_bell_duration 0.0
828
829#: The visual bell duration (in seconds). Flash the screen when a bell
830#: occurs for the specified number of seconds. Set to zero to disable.
831#: The flash is animated, fading in and out over the specified
832#: duration. The easing function used for the fading can be
833#: controlled. For example, 2.0 linear will casuse the flash to fade
834#: in and out linearly. The default if unspecified is to use ease-in-
835#: out which fades slowly at the start, middle and end. You can
836#: specify different easing functions for the fade-in and fade-out
837#: parts, like this: 2.0 ease-in linear. kitty supports all the CSS
838#: easing functions <https://developer.mozilla.org/en-
839#: US/docs/Web/CSS/easing-function>.
840
841# visual_bell_color none
842
843#: The color used by visual bell. Set to none will fall back to
844#: selection background color. If you feel that the visual bell is too
845#: bright, you can set it to a darker color.
846
847# window_alert_on_bell yes
848
849#: Request window attention on bell. Makes the dock icon bounce on
850#: macOS or the taskbar flash on Linux.
851
852# bell_on_tab "🔔 "
853
854#: Some text or a Unicode symbol to show on the tab if a window in the
855#: tab that does not have focus has a bell. If you want to use leading
856#: or trailing spaces, surround the text with quotes. See
857#: tab_title_template for how this is rendered.
858
859#: For backwards compatibility, values of yes, y and true are
860#: converted to the default bell symbol and no, n, false and none are
861#: converted to the empty string.
862
863# command_on_bell none
864
865#: Program to run when a bell occurs. The environment variable
866#: KITTY_CHILD_CMDLINE can be used to get the program running in the
867#: window in which the bell occurred.
868
869# bell_path none
870
871#: Path to a sound file to play as the bell sound. If set to none, the
872#: system default bell sound is used. Must be in a format supported by
873#: the operating systems sound API, such as WAV or OGA on Linux
874#: (libcanberra) or AIFF, MP3 or WAV on macOS (NSSound).
875
876# linux_bell_theme __custom
877
878#: The XDG Sound Theme kitty will use to play the bell sound. Defaults
879#: to the custom theme name specified in the XDG Sound theme
880#: specification <https://specifications.freedesktop.org/sound-theme-
881#: spec/latest/sound_lookup.html>, falling back to the default
882#: freedesktop theme if it does not exist. To change your sound theme
883#: desktop wide, create
884#: :file:~/.local/share/sounds/__custom/index.theme` with the
885#: contents:
886
887#: [Sound Theme]
888
889#: Inherits=name-of-the-sound-theme-you-want-to-use
890
891#: Replace name-of-the-sound-theme-you-want-to-use with the actual
892#: theme name. Now all compliant applications should use sounds from
893#: this theme.
894
895#: }}}
896
897#: Window layout {{{
898
899# remember_window_size yes
900# initial_window_width 640
901# initial_window_height 400
902
903#: If enabled, the OS Window size will be remembered so that new
904#: instances of kitty will have the same size as the previous
905#: instance. If disabled, the OS Window will initially have size
906#: configured by initial_window_width/height, in pixels. You can use a
907#: suffix of "c" on the width/height values to have them interpreted
908#: as number of cells instead of pixels.
909
910# enabled_layouts *
911
912#: The enabled window layouts. A comma separated list of layout names.
913#: The special value all means all layouts. The first listed layout
914#: will be used as the startup layout. Default configuration is all
915#: layouts in alphabetical order. For a list of available layouts, see
916#: the layouts <https://sw.kovidgoyal.net/kitty/overview/#layouts>.
917
918# window_resize_step_cells 2
919# window_resize_step_lines 2
920
921#: The step size (in units of cell width/cell height) to use when
922#: resizing kitty windows in a layout with the shortcut
923#: start_resizing_window. The cells value is used for horizontal
924#: resizing, and the lines value is used for vertical resizing.
925
926# window_border_width 0.5pt
927
928#: The width of window borders. Can be either in pixels (px) or pts
929#: (pt). Values in pts will be rounded to the nearest number of pixels
930#: based on screen resolution. If not specified, the unit is assumed
931#: to be pts. Note that borders are displayed only when more than one
932#: window is visible. They are meant to separate multiple windows.
933
934# draw_minimal_borders yes
935
936#: Draw only the minimum borders needed. This means that only the
937#: borders that separate the window from a neighbor are drawn. Note
938#: that setting a non-zero window_margin_width overrides this and
939#: causes all borders to be drawn.
940
941# window_margin_width 0
942
943#: The window margin (in pts) (blank area outside the border). A
944#: single value sets all four sides. Two values set the vertical and
945#: horizontal sides. Three values set top, horizontal and bottom. Four
946#: values set top, right, bottom and left.
947
948# single_window_margin_width -1
949
950#: The window margin to use when only a single window is visible (in
951#: pts). Negative values will cause the value of window_margin_width
952#: to be used instead. A single value sets all four sides. Two values
953#: set the vertical and horizontal sides. Three values set top,
954#: horizontal and bottom. Four values set top, right, bottom and left.
955
956# window_padding_width 0
957
958#: The window padding (in pts) (blank area between the text and the
959#: window border). A single value sets all four sides. Two values set
960#: the vertical and horizontal sides. Three values set top, horizontal
961#: and bottom. Four values set top, right, bottom and left.
962
963# single_window_padding_width -1
964
965#: The window padding to use when only a single window is visible (in
966#: pts). Negative values will cause the value of window_padding_width
967#: to be used instead. A single value sets all four sides. Two values
968#: set the vertical and horizontal sides. Three values set top,
969#: horizontal and bottom. Four values set top, right, bottom and left.
970
971# placement_strategy center
972
973#: When the window size is not an exact multiple of the cell size, the
974#: cell area of the terminal window will have some extra padding on
975#: the sides. You can control how that padding is distributed with
976#: this option. Using a value of center means the cell area will be
977#: placed centrally. A value of top-left means the padding will be
978#: only at the bottom and right edges. The value can be one of: top-
979#: left, top, top-right, left, center, right, bottom-left, bottom,
980#: bottom-right.
981
982# active_border_color #00ff00
983
984#: The color for the border of the active window. Set this to none to
985#: not draw borders around the active window.
986
987# inactive_border_color #cccccc
988
989#: The color for the border of inactive windows.
990
991# bell_border_color #ff5a00
992
993#: The color for the border of inactive windows in which a bell has
994#: occurred.
995
996# inactive_text_alpha 1.0
997
998#: Fade the text in inactive windows by the specified amount (a number
999#: between zero and one, with zero being fully faded).
1000
1001# hide_window_decorations no
1002
1003#: Hide the window decorations (title-bar and window borders) with
1004#: yes. On macOS, titlebar-only and titlebar-and-corners can be used
1005#: to only hide the titlebar and the rounded corners. Whether this
1006#: works and exactly what effect it has depends on the window
1007#: manager/operating system. Note that the effects of changing this
1008#: option when reloading config are undefined. When using titlebar-
1009#: only, it is useful to also set window_margin_width and
1010#: placement_strategy to prevent the rounded corners from clipping
1011#: text. Or use titlebar-and-corners.
1012
1013# window_logo_path none
1014
1015#: Path to a logo image. Must be in PNG/JPEG/WEBP/GIF/TIFF/BMP format.
1016#: Relative paths are interpreted relative to the kitty config
1017#: directory. The logo is displayed in a corner of every kitty window.
1018#: The position is controlled by window_logo_position. Individual
1019#: windows can be configured to have different logos either using the
1020#: launch action or the remote control
1021#: <https://sw.kovidgoyal.net/kitty/remote-control/> facility.
1022
1023# window_logo_position bottom-right
1024
1025#: Where to position the window logo in the window. The value can be
1026#: one of: top-left, top, top-right, left, center, right, bottom-left,
1027#: bottom, bottom-right.
1028
1029# window_logo_alpha 0.5
1030
1031#: The amount the logo should be faded into the background. With zero
1032#: being fully faded and one being fully opaque.
1033
1034# window_logo_scale 0
1035
1036#: The percentage (0-100] of the window size to which the logo should
1037#: scale. Using a single number means the logo is scaled to that
1038#: percentage of the shortest window dimension, while preserving
1039#: aspect ratio of the logo image.
1040
1041#: Using two numbers means the width and height of the logo are scaled
1042#: to the respective percentage of the window's width and height.
1043
1044#: Using zero as the percentage disables scaling in that dimension. A
1045#: single zero (the default) disables all scaling of the window logo.
1046
1047# resize_debounce_time 0.1 0.5
1048
1049#: The time to wait (in seconds) before asking the program running in
1050#: kitty to resize and redraw the screen during a live resize of the
1051#: OS window, when no new resize events have been received, i.e. when
1052#: resizing is either paused or finished. On platforms such as macOS,
1053#: where the operating system sends events corresponding to the start
1054#: and end of a live resize, the second number is used for redraw-
1055#: after-pause since kitty can distinguish between a pause and end of
1056#: resizing. On such systems the first number is ignored and redraw is
1057#: immediate after end of resize. On other systems only the first
1058#: number is used so that kitty is "ready" quickly after the end of
1059#: resizing, while not also continuously redrawing, to save energy.
1060
1061# resize_in_steps no
1062
1063#: Resize the OS window in steps as large as the cells, instead of
1064#: with the usual pixel accuracy. Combined with initial_window_width
1065#: and initial_window_height in number of cells, this option can be
1066#: used to keep the margins as small as possible when resizing the OS
1067#: window. Note that this does not currently work on Wayland.
1068
1069# visual_window_select_characters 1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ
1070
1071#: The list of characters for visual window selection. For example,
1072#: for selecting a window to focus on with focus_visible_window. The
1073#: value should be a series of unique numbers or alphabets, case
1074#: insensitive, from the set 0-9A-Z\-=[];',./\\`. Specify your
1075#: preference as a string of characters.
1076
1077# confirm_os_window_close -1
1078
1079#: Ask for confirmation when closing an OS window or a tab with at
1080#: least this number of kitty windows in it by window manager (e.g.
1081#: clicking the window close button or pressing the operating system
1082#: shortcut to close windows) or by the close_tab action. A value of
1083#: zero disables confirmation. This confirmation also applies to
1084#: requests to quit the entire application (all OS windows, via the
1085#: quit action). Negative values are converted to positive ones,
1086#: however, with shell_integration enabled, using negative values
1087#: means windows sitting at a shell prompt are not counted, only
1088#: windows where some command is currently running. You can also have
1089#: backgrounded jobs prevent closing, by adding count-background to
1090#: the setting, for example: -1 count-background. Note that if you
1091#: want confirmation when closing individual windows, you can map the
1092#: close_window_with_confirmation action.
1093
1094#: }}}
1095
1096#: Tab bar {{{
1097
1098tab_bar_edge top
1099
1100#: The edge to show the tab bar on, top or bottom.
1101
1102tab_bar_margin_width 1.0
1103
1104#: The margin to the left and right of the tab bar (in pts).
1105
1106tab_bar_margin_height 1.0 1.0
1107
1108#: The margin above and below the tab bar (in pts). The first number
1109#: is the margin between the edge of the OS Window and the tab bar.
1110#: The second number is the margin between the tab bar and the
1111#: contents of the current tab.
1112
1113tab_bar_style separator
1114
1115#: The tab bar style, can be one of:
1116
1117#: fade
1118#: Each tab's edges fade into the background color. (See also tab_fade)
1119#: slant
1120#: Tabs look like the tabs in a physical file.
1121#: separator
1122#: Tabs are separated by a configurable separator. (See also
1123#: tab_separator)
1124#: powerline
1125#: Tabs are shown as a continuous line with "fancy" separators.
1126#: (See also tab_powerline_style)
1127#: custom
1128#: A user-supplied Python function called draw_tab is loaded from the file
1129#: tab_bar.py in the kitty config directory. For examples of how to
1130#: write such a function, see the functions named draw_tab_with_* in
1131#: kitty's source code: kitty/tab_bar.py. See also
1132#: this discussion <https://github.com/kovidgoyal/kitty/discussions/4447>
1133#: for examples from kitty users.
1134#: hidden
1135#: The tab bar is hidden. If you use this, you might want to create
1136#: a mapping for the select_tab action which presents you with a list of
1137#: tabs and allows for easy switching to a tab.
1138
1139# tab_bar_align left
1140
1141#: The horizontal alignment of the tab bar, can be one of: left,
1142#: center, right.
1143
1144tab_bar_min_tabs 1
1145
1146#: The minimum number of tabs that must exist before the tab bar is
1147#: shown.
1148
1149# tab_switch_strategy previous
1150
1151#: The algorithm to use when switching to a tab when the current tab
1152#: is closed. The default of previous will switch to the last used
1153#: tab. A value of left will switch to the tab to the left of the
1154#: closed tab. A value of right will switch to the tab to the right of
1155#: the closed tab. A value of last will switch to the right-most tab.
1156
1157# tab_fade 0.25 0.5 0.75 1
1158
1159#: Control how each tab fades into the background when using fade for
1160#: the tab_bar_style. Each number is an alpha (between zero and one)
1161#: that controls how much the corresponding cell fades into the
1162#: background, with zero being no fade and one being full fade. You
1163#: can change the number of cells used by adding/removing entries to
1164#: this list.
1165
1166# tab_separator " |"
1167
1168#: The separator between tabs in the tab bar when using separator as
1169#: the tab_bar_style.
1170
1171# tab_powerline_style angled
1172
1173#: The powerline separator style between tabs in the tab bar when
1174#: using powerline as the tab_bar_style, can be one of: angled,
1175#: slanted, round.
1176
1177# tab_activity_symbol none
1178
1179#: Some text or a Unicode symbol to show on the tab if a window in the
1180#: tab that does not have focus has some activity. If you want to use
1181#: leading or trailing spaces, surround the text with quotes. See
1182#: tab_title_template for how this is rendered.
1183
1184# tab_title_max_length 0
1185
1186#: The maximum number of cells that can be used to render the text in
1187#: a tab. A value of zero means that no limit is applied.
1188
1189# tab_title_template "{fmt.fg.red}{bell_symbol}{activity_symbol}{fmt.fg.tab}{tab.last_focused_progress_percent}{title}"
1190
1191#: A template to render the tab title. The default just renders the
1192#: title with optional symbols for bell and activity. If you wish to
1193#: include the tab-index as well, use something like: {index}:{title}.
1194#: Useful if you have shortcuts mapped for goto_tab N. If you prefer
1195#: to see the index as a superscript, use {sup.index}. All data
1196#: available is:
1197
1198#: title
1199#: The current tab title.
1200#: index
1201#: The tab index usable with goto_tab N goto_tab shortcuts.
1202#: layout_name
1203#: The current layout name.
1204#: num_windows
1205#: The number of windows in the tab.
1206#: num_window_groups
1207#: The number of window groups (a window group is a window and all of its overlay windows) in the tab.
1208#: tab.active_wd
1209#: The working directory of the currently active window in the tab
1210#: (expensive, requires syscall). Use tab.active_oldest_wd to get
1211#: the directory of the oldest foreground process rather than the newest.
1212#: tab.active_exe
1213#: The name of the executable running in the foreground of the currently
1214#: active window in the tab (expensive, requires syscall). Use
1215#: tab.active_oldest_exe for the oldest foreground process.
1216#: max_title_length
1217#: The maximum title length available.
1218#: keyboard_mode
1219#: The name of the current keyboard mode <https://sw.kovidgoyal.net/kitty/mapping/#modal-mappings> or the empty string if no keyboard mode is active.
1220#: tab.last_focused_progress_percent
1221#: If a command running in a window reports the progress for a task, show this progress as a percentage
1222#: from the most recently focused window in the tab. Empty string if no progress is reported.
1223#: tab.progress_percent
1224#: If a command running in a window reports the progress for a task, show this progress as a percentage
1225#: from all windows in the tab, averaged. Empty string is no progress is reported.
1226
1227#: Note that formatting is done by Python's string formatting
1228#: machinery, so you can use, for instance, {layout_name[:2].upper()}
1229#: to show only the first two letters of the layout name, upper-cased.
1230#: If you want to style the text, you can use styling directives, for
1231#: example:
1232#: `{fmt.fg.red}red{fmt.fg.tab}normal{fmt.bg._00FF00}greenbg{fmt.bg.tab}`.
1233#: Similarly, for bold and italic:
1234#: `{fmt.bold}bold{fmt.nobold}normal{fmt.italic}italic{fmt.noitalic}`.
1235#: The 256 eight terminal colors can be used as `fmt.fg.color0`
1236#: through `fmt.fg.color255`. Note that for backward compatibility, if
1237#: {bell_symbol} or {activity_symbol} are not present in the template,
1238#: they are prepended to it.
1239
1240# active_tab_title_template none
1241
1242#: Template to use for active tabs. If not specified falls back to
1243#: tab_title_template.
1244
1245# active_tab_foreground #000
1246# active_tab_background #eee
1247# active_tab_font_style bold-italic
1248# inactive_tab_foreground #444
1249# inactive_tab_background #999
1250# inactive_tab_font_style normal
1251
1252#: Tab bar colors and styles.
1253
1254tab_bar_background #eaeaea
1255
1256#: Background color for the tab bar. Defaults to using the terminal
1257#: background color.
1258
1259# tab_bar_margin_color none
1260
1261#: Color for the tab bar margin area. Defaults to using the terminal
1262#: background color for margins above and below the tab bar. For side
1263#: margins the default color is chosen to match the background color
1264#: of the neighboring tab.
1265
1266#: }}}
1267
1268#: Color scheme {{{
1269
1270# foreground #dddddd
1271# background #000000
1272
1273#: The foreground and background colors.
1274
1275background_opacity 0.9
1276
1277#: The opacity of the background. A number between zero and one, where
1278#: one is opaque and zero is fully transparent. This will only work if
1279#: supported by the OS (for instance, when using a compositor under
1280#: X11). Note that it only sets the background color's opacity in
1281#: cells that have the same background color as the default terminal
1282#: background, so that things like the status bar in vim, powerline
1283#: prompts, etc. still look good. But it means that if you use a color
1284#: theme with a background color in your editor, it will not be
1285#: rendered as transparent. Instead you should change the default
1286#: background color in your kitty config and not use a background
1287#: color in the editor color scheme. Or use the escape codes to set
1288#: the terminals default colors in a shell script to launch your
1289#: editor. See also transparent_background_colors. Be aware that using
1290#: a value less than 1.0 is a (possibly significant) performance hit.
1291#: When using a low value for this setting, it is desirable that you
1292#: set the background color to a color the matches the general color
1293#: of the desktop background, for best text rendering. Note that to
1294#: workaround window managers not doing gamma-corrected blending kitty
1295#: makes background_opacity non-linear which means, especially for
1296#: light backgrounds you might need to make the value much lower than
1297#: you expect to get good results, see 6218
1298#: <https://github.com/kovidgoyal/kitty/issues/6218> for details.
1299
1300#: If you want to dynamically change transparency of windows, set
1301#: dynamic_background_opacity to yes (this is off by default as it has
1302#: a performance cost). Changing this option when reloading the config
1303#: will only work if dynamic_background_opacity was enabled in the
1304#: original config.
1305
1306# background_blur 0
1307
1308#: Set to a positive value to enable background blur (blurring of the
1309#: visuals behind a transparent window) on platforms that support it.
1310#: Only takes effect when background_opacity is less than one. On
1311#: macOS, this will also control the blur radius (amount of blurring).
1312#: Setting it to too high a value will cause severe performance issues
1313#: and/or rendering artifacts. Usually, values up to 64 work well.
1314#: Note that this might cause performance issues, depending on how the
1315#: platform implements it, so use with care. Currently supported on
1316#: macOS and KDE.
1317
1318# background_image none
1319
1320#: Path to a background image. Must be in PNG/JPEG/WEBP/TIFF/GIF/BMP
1321#: format.
1322
1323# background_image_layout tiled
1324
1325#: Whether to tile, scale or clamp the background image. The value can
1326#: be one of tiled, mirror-tiled, scaled, clamped, centered or
1327#: cscaled. The scaled and cscaled values scale the image to the
1328#: window size, with cscaled preserving the image aspect ratio.
1329
1330# background_image_linear no
1331
1332#: When background image is scaled, whether linear interpolation
1333#: should be used.
1334
1335# transparent_background_colors
1336
1337#: A space separated list of upto 7 colors, with opacity. When the
1338#: background color of a cell matches one of these colors, it is
1339#: rendered semi-transparent using the specified opacity.
1340
1341#: Useful in more complex UIs like editors where you could want more
1342#: than a single background color to be rendered as transparent, for
1343#: instance, for a cursor highlight line background or a highlighted
1344#: block. Terminal applications can set this color using The kitty
1345#: color control <https://sw.kovidgoyal.net/kitty/color-stack/#color-
1346#: control> escape code.
1347
1348#: The syntax for specifying colors is: color@opacity, where the
1349#: @opacity part is optional. When unspecified, the value of
1350#: background_opacity is used. For example::
1351
1352#: transparent_background_colors red@0.5 #00ff00@0.3
1353
1354# dynamic_background_opacity no
1355
1356#: Allow changing of the background_opacity dynamically, using either
1357#: keyboard shortcuts (increase_background_opacity and
1358#: decrease_background_opacity) or the remote control facility.
1359#: Changing this option by reloading the config is not supported.
1360
1361# background_tint 0.0
1362
1363#: How much to tint the background image by the background color. This
1364#: option makes it easier to read the text. Tinting is done using the
1365#: current background color for each window. This option applies only
1366#: if background_opacity is set and transparent windows are supported
1367#: or background_image is set.
1368
1369# background_tint_gaps 1.0
1370
1371#: How much to tint the background image at the window gaps by the
1372#: background color, after applying background_tint. Since this is
1373#: multiplicative with background_tint, it can be used to lighten the
1374#: tint over the window gaps for a *separated* look.
1375
1376# dim_opacity 0.4
1377
1378#: How much to dim text that has the DIM/FAINT attribute set. One
1379#: means no dimming and zero means fully dimmed (i.e. invisible).
1380
1381# selection_foreground #000000
1382# selection_background #fffacd
1383
1384#: The foreground and background colors for text selected with the
1385#: mouse. Setting both of these to none will cause a "reverse video"
1386#: effect for selections, where the selection will be the cell text
1387#: color and the text will become the cell background color. Setting
1388#: only selection_foreground to none will cause the foreground color
1389#: to be used unchanged. Note that these colors can be overridden by
1390#: the program running in the terminal.
1391
1392#: The color table {{{
1393
1394#: The 256 terminal colors. There are 8 basic colors, each color has a
1395#: dull and bright version, for the first 16 colors. You can set the
1396#: remaining 240 colors as color16 to color255.
1397
1398# color0 #000000
1399# color8 #767676
1400
1401#: black
1402
1403# color1 #cc0403
1404# color9 #f2201f
1405
1406#: red
1407
1408# color2 #19cb00
1409# color10 #23fd00
1410
1411#: green
1412
1413# color3 #cecb00
1414# color11 #fffd00
1415
1416#: yellow
1417
1418# color4 #0d73cc
1419# color12 #1a8fff
1420
1421#: blue
1422
1423# color5 #cb1ed1
1424# color13 #fd28ff
1425
1426#: magenta
1427
1428# color6 #0dcdcd
1429# color14 #14ffff
1430
1431#: cyan
1432
1433# color7 #dddddd
1434# color15 #ffffff
1435
1436#: white
1437
1438# mark1_foreground black
1439
1440#: Color for marks of type 1
1441
1442# mark1_background #98d3cb
1443
1444#: Color for marks of type 1 (light steel blue)
1445
1446# mark2_foreground black
1447
1448#: Color for marks of type 2
1449
1450# mark2_background #f2dcd3
1451
1452#: Color for marks of type 1 (beige)
1453
1454# mark3_foreground black
1455
1456#: Color for marks of type 3
1457
1458# mark3_background #f274bc
1459
1460#: Color for marks of type 3 (violet)
1461
1462#: }}}
1463
1464#: }}}
1465
1466#: Advanced {{{
1467
1468# shell .
1469
1470#: The shell program to execute. The default value of . means to use
1471#: the value of of the SHELL environment variable or if unset,
1472#: whatever shell is set as the default shell for the current user.
1473#: Note that on macOS if you change this, you might need to add
1474#: --login and --interactive to ensure that the shell starts in
1475#: interactive mode and reads its startup rc files. Environment
1476#: variables are expanded in this setting.
1477
1478# editor .
1479
1480#: The terminal based text editor (such as vim or nano) to use when
1481#: editing the kitty config file or similar tasks.
1482
1483#: The default value of . means to use the environment variables
1484#: VISUAL and EDITOR in that order. If these variables aren't set,
1485#: kitty will run your shell ($SHELL -l -i -c env) to see if your
1486#: shell startup rc files set VISUAL or EDITOR. If that doesn't work,
1487#: kitty will cycle through various known editors (vim, emacs, etc.)
1488#: and take the first one that exists on your system.
1489
1490# close_on_child_death no
1491
1492#: Close the window when the child process (usually the shell) exits.
1493#: With the default value no, the terminal will remain open when the
1494#: child exits as long as there are still other processes outputting
1495#: to the terminal (for example disowned or backgrounded processes).
1496#: When enabled with yes, the window will close as soon as the child
1497#: process exits. Note that setting it to yes means that any
1498#: background processes still using the terminal can fail silently
1499#: because their stdout/stderr/stdin no longer work.
1500
1501# remote_control_password
1502
1503#: Allow other programs to control kitty using passwords. This option
1504#: can be specified multiple times to add multiple passwords. If no
1505#: passwords are present kitty will ask the user for permission if a
1506#: program tries to use remote control with a password. A password can
1507#: also *optionally* be associated with a set of allowed remote
1508#: control actions. For example::
1509
1510#: remote_control_password "my passphrase" get-colors set-colors focus-window focus-tab
1511
1512#: Only the specified actions will be allowed when using this
1513#: password. Glob patterns can be used too, for example::
1514
1515#: remote_control_password "my passphrase" set-tab-* resize-*
1516
1517#: To get a list of available actions, run::
1518
1519#: kitten @ --help
1520
1521#: A set of actions to be allowed when no password is sent can be
1522#: specified by using an empty password. For example::
1523
1524#: remote_control_password "" *-colors
1525
1526#: Finally, the path to a python module can be specified that provides
1527#: a function is_cmd_allowed that is used to check every remote
1528#: control command. For example::
1529
1530#: remote_control_password "my passphrase" my_rc_command_checker.py
1531
1532#: Relative paths are resolved from the kitty configuration directory.
1533#: See rc_custom_auth <https://sw.kovidgoyal.net/kitty/remote-
1534#: control/#rc-custom-auth> for details.
1535
1536# allow_remote_control no
1537
1538#: Allow other programs to control kitty. If you turn this on, other
1539#: programs can control all aspects of kitty, including sending text
1540#: to kitty windows, opening new windows, closing windows, reading the
1541#: content of windows, etc. Note that this even works over SSH
1542#: connections. The default setting of no prevents any form of remote
1543#: control. The meaning of the various values are:
1544
1545#: password
1546#: Remote control requests received over both the TTY device and the socket
1547#: are confirmed based on passwords, see remote_control_password.
1548
1549#: socket-only
1550#: Remote control requests received over a socket are accepted
1551#: unconditionally. Requests received over the TTY are denied.
1552#: See listen_on.
1553
1554#: socket
1555#: Remote control requests received over a socket are accepted
1556#: unconditionally. Requests received over the TTY are confirmed based on
1557#: password.
1558
1559#: no
1560#: Remote control is completely disabled.
1561
1562#: yes
1563#: Remote control requests are always accepted.
1564
1565# listen_on none
1566
1567#: Listen to the specified socket for remote control connections. Note
1568#: that this will apply to all kitty instances. It can be overridden
1569#: by the kitty --listen-on command line option. For UNIX sockets,
1570#: such as unix:${TEMP}/mykitty or unix:@mykitty (on Linux).
1571#: Environment variables are expanded and relative paths are resolved
1572#: with respect to the temporary directory. If {kitty_pid} is present,
1573#: then it is replaced by the PID of the kitty process, otherwise the
1574#: PID of the kitty process is appended to the value, with a hyphen.
1575#: For TCP sockets such as tcp:localhost:0 a random port is always
1576#: used even if a non-zero port number is specified. See the help for
1577#: kitty --listen-on for more details. Note that this will be ignored
1578#: unless allow_remote_control is set to either: yes, socket or
1579#: socket-only. Changing this option by reloading the config is not
1580#: supported.
1581
1582# env
1583
1584#: Specify the environment variables to be set in all child processes.
1585#: Using the name with an equal sign (e.g. env VAR=) will set it to
1586#: the empty string. Specifying only the name (e.g. env VAR) will
1587#: remove the variable from the child process' environment. Note that
1588#: environment variables are expanded recursively, for example::
1589
1590#: env VAR1=a
1591#: env VAR2=${HOME}/${VAR1}/b
1592
1593#: The value of VAR2 will be <path to home directory>/a/b.
1594
1595# filter_notification
1596
1597#: Specify rules to filter out notifications sent by applications
1598#: running in kitty. Can be specified multiple times to create
1599#: multiple filter rules. A rule specification is of the form
1600#: field:regexp. A filter rule can match on any of the fields: title,
1601#: body, app, type. The special value of all filters out all
1602#: notifications. Rules can be combined using Boolean operators. Some
1603#: examples::
1604
1605#: filter_notification title:hello or body:"abc.*def"
1606#: # filter out notification from vim except for ones about updates, (?i)
1607#: # makes matching case insensitive.
1608#: filter_notification app:"[ng]?vim" and not body:"(?i)update"
1609#: # filter out all notifications
1610#: filter_notification all
1611
1612#: The field app is the name of the application sending the
1613#: notification and type is the type of the notification. Not all
1614#: applications will send these fields, so you can also match on the
1615#: title and body of the notification text. More sophisticated
1616#: programmatic filtering and custom actions on notifications can be
1617#: done by creating a notifications.py file in the kitty config
1618#: directory (~/.config/kitty). An annotated sample is available
1619#: <https://github.com/kovidgoyal/kitty/blob/master/docs/notifications.py>.
1620
1621# watcher
1622
1623#: Path to python file which will be loaded for watchers
1624#: <https://sw.kovidgoyal.net/kitty/launch/#watchers>. Can be
1625#: specified more than once to load multiple watchers. The watchers
1626#: will be added to every kitty window. Relative paths are resolved
1627#: relative to the kitty config directory. Note that reloading the
1628#: config will only affect windows created after the reload.
1629
1630# exe_search_path
1631
1632#: Control where kitty finds the programs to run. The default search
1633#: order is: First search the system wide PATH, then ~/.local/bin and
1634#: ~/bin. If still not found, the PATH defined in the login shell
1635#: after sourcing all its startup files is tried. Finally, if present,
1636#: the PATH specified by the env option is tried.
1637
1638#: This option allows you to prepend, append, or remove paths from
1639#: this search order. It can be specified multiple times for multiple
1640#: paths. A simple path will be prepended to the search order. A path
1641#: that starts with the + sign will be append to the search order,
1642#: after ~/bin above. A path that starts with the - sign will be
1643#: removed from the entire search order. For example::
1644
1645#: exe_search_path /some/prepended/path
1646#: exe_search_path +/some/appended/path
1647#: exe_search_path -/some/excluded/path
1648
1649# update_check_interval 24
1650
1651#: The interval to periodically check if an update to kitty is
1652#: available (in hours). If an update is found, a system notification
1653#: is displayed informing you of the available update. The default is
1654#: to check every 24 hours, set to zero to disable. Update checking is
1655#: only done by the official binary builds. Distro packages or source
1656#: builds do not do update checking. Changing this option by reloading
1657#: the config is not supported.
1658
1659# startup_session none
1660
1661#: Path to a session file to use for all kitty instances. Can be
1662#: overridden by using the kitty --session =none command line option
1663#: for individual instances. See sessions
1664#: <https://sw.kovidgoyal.net/kitty/overview/#sessions> in the kitty
1665#: documentation for details. Note that relative paths are interpreted
1666#: with respect to the kitty config directory. Environment variables
1667#: in the path are expanded. Changing this option by reloading the
1668#: config is not supported. Note that if kitty is invoked with command
1669#: line arguments specifying a command to run, this option is ignored.
1670
1671# clipboard_control write-clipboard write-primary read-clipboard-ask read-primary-ask
1672
1673#: Allow programs running in kitty to read and write from the
1674#: clipboard. You can control exactly which actions are allowed. The
1675#: possible actions are: write-clipboard, read-clipboard, write-
1676#: primary, read-primary, read-clipboard-ask, read-primary-ask. The
1677#: default is to allow writing to the clipboard and primary selection
1678#: and to ask for permission when a program tries to read from the
1679#: clipboard. Note that disabling the read confirmation is a security
1680#: risk as it means that any program, even the ones running on a
1681#: remote server via SSH can read your clipboard. See also
1682#: clipboard_max_size.
1683
1684# clipboard_max_size 512
1685
1686#: The maximum size (in MB) of data from programs running in kitty
1687#: that will be stored for writing to the system clipboard. A value of
1688#: zero means no size limit is applied. See also clipboard_control.
1689
1690# file_transfer_confirmation_bypass
1691
1692#: The password that can be supplied to the file transfer kitten
1693#: <https://sw.kovidgoyal.net/kitty/kittens/transfer/> to skip the
1694#: transfer confirmation prompt. This should only be used when
1695#: initiating transfers from trusted computers, over trusted networks
1696#: or encrypted transports, as it allows any programs running on the
1697#: remote machine to read/write to the local filesystem, without
1698#: permission.
1699
1700# allow_hyperlinks yes
1701
1702#: Process hyperlink escape sequences (OSC 8). If disabled OSC 8
1703#: escape sequences are ignored. Otherwise they become clickable
1704#: links, that you can click with the mouse or by using the hints
1705#: kitten <https://sw.kovidgoyal.net/kitty/kittens/hints/>. The
1706#: special value of ask means that kitty will ask before opening the
1707#: link when clicked.
1708
1709# shell_integration enabled
1710
1711#: Enable shell integration on supported shells. This enables features
1712#: such as jumping to previous prompts, browsing the output of the
1713#: previous command in a pager, etc. on supported shells. Set to
1714#: disabled to turn off shell integration, completely. It is also
1715#: possible to disable individual features, set to a space separated
1716#: list of these values: no-rc, no-cursor, no-title, no-cwd, no-
1717#: prompt-mark, no-complete, no-sudo. See Shell integration
1718#: <https://sw.kovidgoyal.net/kitty/shell-integration/> for details.
1719
1720# allow_cloning ask
1721
1722#: Control whether programs running in the terminal can request new
1723#: windows to be created. The canonical example is clone-in-kitty
1724#: <https://sw.kovidgoyal.net/kitty/shell-integration/#clone-shell>.
1725#: By default, kitty will ask for permission for each clone request.
1726#: Allowing cloning unconditionally gives programs running in the
1727#: terminal (including over SSH) permission to execute arbitrary code,
1728#: as the user who is running the terminal, on the computer that the
1729#: terminal is running on.
1730
1731# clone_source_strategies venv,conda,env_var,path
1732
1733#: Control what shell code is sourced when running clone-in-kitty in
1734#: the newly cloned window. The supported strategies are:
1735
1736#: venv
1737#: Source the file $VIRTUAL_ENV/bin/activate. This is used by the
1738#: Python stdlib venv module and allows cloning venvs automatically.
1739#: conda
1740#: Run conda activate $CONDA_DEFAULT_ENV. This supports the virtual
1741#: environments created by conda.
1742#: env_var
1743#: Execute the contents of the environment variable
1744#: KITTY_CLONE_SOURCE_CODE with eval.
1745#: path
1746#: Source the file pointed to by the environment variable
1747#: KITTY_CLONE_SOURCE_PATH.
1748
1749#: This option must be a comma separated list of the above values.
1750#: Only the first valid match, in the order specified, is sourced.
1751
1752# notify_on_cmd_finish never
1753
1754#: Show a desktop notification when a long-running command finishes
1755#: (needs shell_integration). The possible values are:
1756
1757#: never
1758#: Never send a notification.
1759
1760#: unfocused
1761#: Only send a notification when the window does not have keyboard focus.
1762
1763#: invisible
1764#: Only send a notification when the window both is unfocused and not visible
1765#: to the user, for example, because it is in an inactive tab or its OS window
1766#: is not currently visible (on platforms that support OS window visibility querying
1767#: this considers an OS Window visible iff it is active).
1768
1769#: always
1770#: Always send a notification, regardless of window state.
1771
1772#: There are two optional arguments:
1773
1774#: First, the minimum duration for what is considered a long running
1775#: command. The default is 5 seconds. Specify a second argument to set
1776#: the duration. For example: invisible 15. Do not set the value too
1777#: small, otherwise a command that launches a new OS Window and exits
1778#: will spam a notification.
1779
1780#: Second, the action to perform. The default is notify. The possible
1781#: values are:
1782
1783#: notify
1784#: Send a desktop notification. The subsequent arguments are optional and specify when
1785#: the notification is automatically cleared. The set of possible events when the notification is
1786#: cleared are: focus and next. focus means that when the notification
1787#: policy is unfocused or invisible the notification is automatically cleared
1788#: when the window regains focus. The value of next means that the previous notification
1789#: is cleared when the next notification is shown. The default when no arguments are specified
1790#: is: focus next.
1791
1792#: bell
1793#: Ring the terminal bell.
1794
1795#: command
1796#: Run a custom command. All subsequent arguments are the cmdline to run.
1797
1798#: Some more examples::
1799
1800#: # Send a notification when a command takes more than 5 seconds in an unfocused window
1801#: notify_on_cmd_finish unfocused
1802#: # Send a notification when a command takes more than 10 seconds in a invisible window
1803#: notify_on_cmd_finish invisible 10.0
1804#: # Ring a bell when a command takes more than 10 seconds in a invisible window
1805#: notify_on_cmd_finish invisible 10.0 bell
1806#: # Run 'notify-send' when a command takes more than 10 seconds in a invisible window
1807#: # Here %c is replaced by the current command line and %s by the job exit code
1808#: notify_on_cmd_finish invisible 10.0 command notify-send "job finished with status: %s" %c
1809#: # Do not clear previous notification when next command finishes or window regains focus
1810#: notify_on_cmd_finish invisible 5.0 notify
1811
1812# term xterm-kitty
1813
1814#: The value of the TERM environment variable to set. Changing this
1815#: can break many terminal programs, only change it if you know what
1816#: you are doing, not because you read some advice on "Stack Overflow"
1817#: to change it. The TERM variable is used by various programs to get
1818#: information about the capabilities and behavior of the terminal. If
1819#: you change it, depending on what programs you run, and how
1820#: different the terminal you are changing it to is, various things
1821#: from key-presses, to colors, to various advanced features may not
1822#: work. Changing this option by reloading the config will only affect
1823#: newly created windows.
1824
1825# terminfo_type path
1826
1827#: The value of the TERMINFO environment variable to set. This
1828#: variable is used by programs running in the terminal to search for
1829#: terminfo databases. The default value of path causes kitty to set
1830#: it to a filesystem location containing the kitty terminfo database.
1831#: A value of direct means put the entire database into the env var
1832#: directly. This can be useful when connecting to containers, for
1833#: example. But, note that not all software supports this. A value of
1834#: none means do not touch the variable.
1835
1836# forward_stdio no
1837
1838#: Forward STDOUT and STDERR of the kitty process to child processes.
1839#: This is useful for debugging as it allows child processes to print
1840#: to kitty's STDOUT directly. For example, echo hello world
1841#: >&$KITTY_STDIO_FORWARDED in a shell will print to the parent
1842#: kitty's STDOUT. Sets the KITTY_STDIO_FORWARDED=fdnum environment
1843#: variable so child processes know about the forwarding. Note that on
1844#: macOS this prevents the shell from being run via the login utility
1845#: so getlogin() will not work in programs run in this session.
1846
1847# menu_map
1848
1849#: Specify entries for various menus in kitty. Currently only the
1850#: global menubar on macOS is supported. For example::
1851
1852#: menu_map global "Actions::Launch something special" launch --hold --type=os-window sh -c "echo hello world"
1853
1854#: This will create a menu entry named "Launch something special" in
1855#: an "Actions" menu in the macOS global menubar. Sub-menus can be
1856#: created by adding more levels separated by the :: characters.
1857
1858#: }}}
1859
1860#: OS specific tweaks {{{
1861
1862# wayland_titlebar_color system
1863
1864#: The color of the kitty window's titlebar on Wayland systems with
1865#: client side window decorations such as GNOME. A value of system
1866#: means to use the default system colors, a value of background means
1867#: to use the background color of the currently active kitty window
1868#: and finally you can use an arbitrary color, such as #12af59 or red.
1869
1870# macos_titlebar_color system
1871
1872#: The color of the kitty window's titlebar on macOS. A value of
1873#: system means to use the default system color, light or dark can
1874#: also be used to set it explicitly. A value of background means to
1875#: use the background color of the currently active window and finally
1876#: you can use an arbitrary color, such as #12af59 or red. WARNING:
1877#: This option works by using a hack when arbitrary color (or
1878#: background) is configured, as there is no proper Cocoa API for it.
1879#: It sets the background color of the entire window and makes the
1880#: titlebar transparent. As such it is incompatible with
1881#: background_opacity. If you want to use both, you are probably
1882#: better off just hiding the titlebar with hide_window_decorations.
1883
1884# macos_option_as_alt no
1885
1886#: Use the Option key as an Alt key on macOS. With this set to no,
1887#: kitty will use the macOS native Option+Key to enter Unicode
1888#: character behavior. This will break any Alt+Key keyboard shortcuts
1889#: in your terminal programs, but you can use the macOS Unicode input
1890#: technique. You can use the values: left, right or both to use only
1891#: the left, right or both Option keys as Alt, instead. Note that
1892#: kitty itself always treats Option the same as Alt. This means you
1893#: cannot use this option to configure different kitty shortcuts for
1894#: Option+Key vs. Alt+Key. Also, any kitty shortcuts using
1895#: Option/Alt+Key will take priority, so that any such key presses
1896#: will not be passed to terminal programs running inside kitty.
1897#: Changing this option by reloading the config is not supported.
1898
1899# macos_hide_from_tasks no
1900
1901#: Hide the kitty window from running tasks on macOS (⌘+Tab and the
1902#: Dock). Changing this option by reloading the config is not
1903#: supported.
1904
1905# macos_quit_when_last_window_closed no
1906
1907#: Have kitty quit when all the top-level windows are closed on macOS.
1908#: By default, kitty will stay running, even with no open windows, as
1909#: is the expected behavior on macOS.
1910
1911# macos_window_resizable yes
1912
1913#: Disable this if you want kitty top-level OS windows to not be
1914#: resizable on macOS.
1915
1916# macos_thicken_font 0
1917
1918#: Draw an extra border around the font with the given width, to
1919#: increase legibility at small font sizes on macOS. For example, a
1920#: value of 0.75 will result in rendering that looks similar to sub-
1921#: pixel antialiasing at common font sizes. Note that in modern kitty,
1922#: this option is obsolete (although still supported). Consider using
1923#: text_composition_strategy instead.
1924
1925# macos_traditional_fullscreen no
1926
1927#: Use the macOS traditional full-screen transition, that is faster,
1928#: but less pretty.
1929
1930# macos_show_window_title_in all
1931
1932#: Control where the window title is displayed on macOS. A value of
1933#: window will show the title of the currently active window at the
1934#: top of the macOS window. A value of menubar will show the title of
1935#: the currently active window in the macOS global menu bar, making
1936#: use of otherwise wasted space. A value of all will show the title
1937#: in both places, and none hides the title. See
1938#: macos_menubar_title_max_length for how to control the length of the
1939#: title in the menu bar.
1940
1941# macos_menubar_title_max_length 0
1942
1943#: The maximum number of characters from the window title to show in
1944#: the macOS global menu bar. Values less than one means that there is
1945#: no maximum limit.
1946
1947# macos_custom_beam_cursor no
1948
1949#: Use a custom mouse cursor for macOS that is easier to see on both
1950#: light and dark backgrounds. Nowadays, the default macOS cursor
1951#: already comes with a white border. WARNING: this might make your
1952#: mouse cursor invisible on dual GPU machines. Changing this option
1953#: by reloading the config is not supported.
1954
1955# macos_colorspace srgb
1956
1957#: The colorspace in which to interpret terminal colors. The default
1958#: of srgb will cause colors to match those seen in web browsers. The
1959#: value of default will use whatever the native colorspace of the
1960#: display is. The value of displayp3 will use Apple's special
1961#: snowflake display P3 color space, which will result in over
1962#: saturated (brighter) colors with some color shift. Reloading
1963#: configuration will change this value only for newly created OS
1964#: windows.
1965
1966# linux_display_server auto
1967
1968#: Choose between Wayland and X11 backends. By default, an appropriate
1969#: backend based on the system state is chosen automatically. Set it
1970#: to x11 or wayland to force the choice. Changing this option by
1971#: reloading the config is not supported.
1972
1973# wayland_enable_ime yes
1974
1975#: Enable Input Method Extension on Wayland. This is typically used
1976#: for inputting text in East Asian languages. However, its
1977#: implementation in Wayland is often buggy and introduces latency
1978#: into the input loop, so disable this if you know you dont need it.
1979#: Changing this option by reloading the config is not supported, it
1980#: will not have any effect.
1981
1982#: }}}
1983
1984#: Keyboard shortcuts {{{
1985
1986#: Keys are identified simply by their lowercase Unicode characters.
1987#: For example: a for the A key, [ for the left square bracket key,
1988#: etc. For functional keys, such as Enter or Escape, the names are
1989#: present at Functional key definitions
1990#: <https://sw.kovidgoyal.net/kitty/keyboard-protocol/#functional>.
1991#: For modifier keys, the names are ctrl (control, ⌃), shift (⇧), alt
1992#: (opt, option, ⌥), super (cmd, command, ⌘).
1993
1994#: Simple shortcut mapping is done with the map directive. For full
1995#: details on advanced mapping including modal and per application
1996#: maps, see mapping <https://sw.kovidgoyal.net/kitty/mapping/>. Some
1997#: quick examples to illustrate common tasks::
1998
1999#: # unmap a keyboard shortcut, passing it to the program running in kitty
2000#: map kitty_mod+space
2001#: # completely ignore a keyboard event
2002#: map ctrl+alt+f1 discard_event
2003#: # combine multiple actions
2004#: map kitty_mod+e combine : new_window : next_layout
2005#: # multi-key shortcuts
2006#: map ctrl+x>ctrl+y>z action
2007
2008#: The full list of actions that can be mapped to key presses is
2009#: available here <https://sw.kovidgoyal.net/kitty/actions/>.
2010
2011# kitty_mod ctrl+shift
2012
2013#: Special modifier key alias for default shortcuts. You can change
2014#: the value of this option to alter all default shortcuts that use
2015#: kitty_mod.
2016
2017# clear_all_shortcuts no
2018
2019#: Remove all shortcut definitions up to this point. Useful, for
2020#: instance, to remove the default shortcuts.
2021
2022# action_alias
2023
2024#: E.g. action_alias launch_tab launch --type=tab --cwd=current
2025
2026#: Define action aliases to avoid repeating the same options in
2027#: multiple mappings. Aliases can be defined for any action and will
2028#: be expanded recursively. For example, the above alias allows you to
2029#: create mappings to launch a new tab in the current working
2030#: directory without duplication::
2031
2032#: map f1 launch_tab vim
2033#: map f2 launch_tab emacs
2034
2035#: Similarly, to alias kitten invocation::
2036
2037#: action_alias hints kitten hints --hints-offset=0
2038
2039# kitten_alias
2040
2041#: E.g. kitten_alias hints hints --hints-offset=0
2042
2043#: Like action_alias above, but specifically for kittens. Generally,
2044#: prefer to use action_alias. This option is a legacy version,
2045#: present for backwards compatibility. It causes all invocations of
2046#: the aliased kitten to be substituted. So the example above will
2047#: cause all invocations of the hints kitten to have the --hints-
2048#: offset=0 option applied.
2049
2050#: Clipboard {{{
2051
2052#: Copy to clipboard
2053
2054# map kitty_mod+c copy_to_clipboard
2055# map cmd+c copy_to_clipboard
2056
2057#:: There is also a copy_or_interrupt action that can be optionally
2058#:: mapped to Ctrl+C. It will copy only if there is a selection and
2059#:: send an interrupt otherwise. Similarly,
2060#:: copy_and_clear_or_interrupt will copy and clear the selection or
2061#:: send an interrupt if there is no selection.
2062
2063#: Paste from clipboard
2064
2065# map kitty_mod+v paste_from_clipboard
2066# map cmd+v paste_from_clipboard
2067
2068#: Paste from selection
2069
2070# map kitty_mod+s paste_from_selection
2071# map shift+insert paste_from_selection
2072
2073#: Pass selection to program
2074
2075# map kitty_mod+o pass_selection_to_program
2076
2077#:: You can also pass the contents of the current selection to any
2078#:: program with pass_selection_to_program. By default, the system's
2079#:: open program is used, but you can specify your own, the selection
2080#:: will be passed as a command line argument to the program. For
2081#:: example::
2082
2083#:: map kitty_mod+o pass_selection_to_program firefox
2084
2085#:: You can pass the current selection to a terminal program running
2086#:: in a new kitty window, by using the @selection placeholder::
2087
2088#:: map kitty_mod+y new_window less @selection
2089
2090#: }}}
2091
2092#: Scrolling {{{
2093
2094#: Scroll line up
2095
2096# map kitty_mod+up scroll_line_up
2097# map kitty_mod+k scroll_line_up
2098# map opt+cmd+page_up scroll_line_up
2099# map cmd+up scroll_line_up
2100
2101#: Scroll line down
2102
2103# map kitty_mod+down scroll_line_down
2104# map kitty_mod+j scroll_line_down
2105# map opt+cmd+page_down scroll_line_down
2106# map cmd+down scroll_line_down
2107
2108#: Scroll page up
2109
2110# map kitty_mod+page_up scroll_page_up
2111# map cmd+page_up scroll_page_up
2112
2113#: Scroll page down
2114
2115# map kitty_mod+page_down scroll_page_down
2116# map cmd+page_down scroll_page_down
2117
2118#: Scroll to top
2119
2120# map kitty_mod+home scroll_home
2121# map cmd+home scroll_home
2122
2123#: Scroll to bottom
2124
2125# map kitty_mod+end scroll_end
2126# map cmd+end scroll_end
2127
2128#: Scroll to previous shell prompt
2129
2130# map kitty_mod+z scroll_to_prompt -1
2131
2132#:: Use a parameter of 0 for scroll_to_prompt to scroll to the last
2133#:: jumped to or the last clicked position. Requires shell
2134#:: integration <https://sw.kovidgoyal.net/kitty/shell-integration/>
2135#:: to work.
2136
2137#: Scroll to next shell prompt
2138
2139# map kitty_mod+x scroll_to_prompt 1
2140
2141#: Browse scrollback buffer in pager
2142
2143# map kitty_mod+h show_scrollback
2144
2145#:: You can pipe the contents of the current screen and history
2146#:: buffer as STDIN to an arbitrary program using launch --stdin-
2147#:: source. For example, the following opens the scrollback buffer in
2148#:: less in an overlay window::
2149
2150#:: map f1 launch --stdin-source=@screen_scrollback --stdin-add-formatting --type=overlay less +G -R
2151
2152#:: For more details on piping screen and buffer contents to external
2153#:: programs, see launch <https://sw.kovidgoyal.net/kitty/launch/>.
2154
2155#: Browse output of the last shell command in pager
2156
2157# map kitty_mod+g show_last_command_output
2158
2159#:: You can also define additional shortcuts to get the command
2160#:: output. For example, to get the first command output on screen::
2161
2162#:: map f1 show_first_command_output_on_screen
2163
2164#:: To get the command output that was last accessed by a keyboard
2165#:: action or mouse action::
2166
2167#:: map f1 show_last_visited_command_output
2168
2169#:: You can pipe the output of the last command run in the shell
2170#:: using the launch action. For example, the following opens the
2171#:: output in less in an overlay window::
2172
2173#:: map f1 launch --stdin-source=@last_cmd_output --stdin-add-formatting --type=overlay less +G -R
2174
2175#:: To get the output of the first command on the screen, use
2176#:: @first_cmd_output_on_screen. To get the output of the last jumped
2177#:: to command, use @last_visited_cmd_output.
2178
2179#:: Requires shell integration
2180#:: <https://sw.kovidgoyal.net/kitty/shell-integration/> to work.
2181
2182#: }}}
2183
2184#: Window management {{{
2185
2186#: New window
2187
2188# map kitty_mod+enter new_window
2189# map cmd+enter new_window
2190
2191#:: You can open a new kitty window running an arbitrary program, for
2192#:: example::
2193
2194#:: map kitty_mod+y launch mutt
2195
2196#:: You can open a new window with the current working directory set
2197#:: to the working directory of the current window using::
2198
2199#:: map ctrl+alt+enter launch --cwd=current
2200
2201#:: You can open a new window that is allowed to control kitty via
2202#:: the kitty remote control facility with launch --allow-remote-
2203#:: control. Any programs running in that window will be allowed to
2204#:: control kitty. For example::
2205
2206#:: map ctrl+enter launch --allow-remote-control some_program
2207
2208#:: You can open a new window next to the currently active window or
2209#:: as the first window, with::
2210
2211#:: map ctrl+n launch --location=neighbor
2212#:: map ctrl+f launch --location=first
2213
2214#:: For more details, see launch
2215#:: <https://sw.kovidgoyal.net/kitty/launch/>.
2216
2217#: New OS window
2218
2219# map kitty_mod+n new_os_window
2220# map cmd+n new_os_window
2221
2222#:: Works like new_window above, except that it opens a top-level OS
2223#:: window. In particular you can use new_os_window_with_cwd to open
2224#:: a window with the current working directory.
2225
2226#: Close window
2227
2228# map kitty_mod+w close_window
2229# map shift+cmd+d close_window
2230
2231#: Next window
2232
2233# map kitty_mod+] next_window
2234
2235#: Previous window
2236
2237# map kitty_mod+[ previous_window
2238
2239#: Move window forward
2240
2241# map kitty_mod+f move_window_forward
2242
2243#: Move window backward
2244
2245# map kitty_mod+b move_window_backward
2246
2247#: Move window to top
2248
2249# map kitty_mod+` move_window_to_top
2250
2251#: Start resizing window
2252
2253# map kitty_mod+r start_resizing_window
2254# map cmd+r start_resizing_window
2255
2256#: First window
2257
2258# map kitty_mod+1 first_window
2259# map cmd+1 first_window
2260
2261#: Second window
2262
2263# map kitty_mod+2 second_window
2264# map cmd+2 second_window
2265
2266#: Third window
2267
2268# map kitty_mod+3 third_window
2269# map cmd+3 third_window
2270
2271#: Fourth window
2272
2273# map kitty_mod+4 fourth_window
2274# map cmd+4 fourth_window
2275
2276#: Fifth window
2277
2278# map kitty_mod+5 fifth_window
2279# map cmd+5 fifth_window
2280
2281#: Sixth window
2282
2283# map kitty_mod+6 sixth_window
2284# map cmd+6 sixth_window
2285
2286#: Seventh window
2287
2288# map kitty_mod+7 seventh_window
2289# map cmd+7 seventh_window
2290
2291#: Eighth window
2292
2293# map kitty_mod+8 eighth_window
2294# map cmd+8 eighth_window
2295
2296#: Ninth window
2297
2298# map kitty_mod+9 ninth_window
2299# map cmd+9 ninth_window
2300
2301#: Tenth window
2302
2303# map kitty_mod+0 tenth_window
2304
2305#: Visually select and focus window
2306
2307# map kitty_mod+f7 focus_visible_window
2308
2309#:: Display overlay numbers and alphabets on the window, and switch
2310#:: the focus to the window when you press the key. When there are
2311#:: only two windows, the focus will be switched directly without
2312#:: displaying the overlay. You can change the overlay characters and
2313#:: their order with option visual_window_select_characters.
2314
2315#: Visually swap window with another
2316
2317# map kitty_mod+f8 swap_with_window
2318
2319#:: Works like focus_visible_window above, but swaps the window.
2320
2321#: }}}
2322
2323#: Tab management {{{
2324
2325#: Next tab
2326
2327# map kitty_mod+right next_tab
2328# map shift+cmd+] next_tab
2329# map ctrl+tab next_tab
2330
2331#: Previous tab
2332
2333# map kitty_mod+left previous_tab
2334# map shift+cmd+[ previous_tab
2335# map ctrl+shift+tab previous_tab
2336
2337#: New tab
2338
2339# map kitty_mod+t new_tab
2340# map cmd+t new_tab
2341
2342#: Close tab
2343
2344# map kitty_mod+q close_tab
2345# map cmd+w close_tab
2346
2347#: Close OS window
2348
2349# map shift+cmd+w close_os_window
2350
2351#: Move tab forward
2352
2353# map kitty_mod+. move_tab_forward
2354
2355#: Move tab backward
2356
2357# map kitty_mod+, move_tab_backward
2358
2359#: Set tab title
2360
2361# map kitty_mod+alt+t set_tab_title
2362# map shift+cmd+i set_tab_title
2363
2364
2365#: You can also create shortcuts to go to specific tabs, with 1 being
2366#: the first tab, 2 the second tab and -1 being the previously active
2367#: tab, -2 being the tab active before the previously active tab and
2368#: so on. Any number larger than the number of tabs goes to the last
2369#: tab and any number less than the number of previously used tabs in
2370#: the history goes to the oldest previously used tab in the history::
2371
2372#: map ctrl+alt+1 goto_tab 1
2373#: map ctrl+alt+2 goto_tab 2
2374
2375#: Just as with new_window above, you can also pass the name of
2376#: arbitrary commands to run when using new_tab and new_tab_with_cwd.
2377#: Finally, if you want the new tab to open next to the current tab
2378#: rather than at the end of the tabs list, use::
2379
2380#: map ctrl+t new_tab !neighbor [optional cmd to run]
2381#: }}}
2382
2383#: Layout management {{{
2384
2385#: Next layout
2386
2387# map kitty_mod+l next_layout
2388
2389
2390#: You can also create shortcuts to switch to specific layouts::
2391
2392#: map ctrl+alt+t goto_layout tall
2393#: map ctrl+alt+s goto_layout stack
2394
2395#: Similarly, to switch back to the previous layout::
2396
2397#: map ctrl+alt+p last_used_layout
2398
2399#: There is also a toggle_layout action that switches to the named
2400#: layout or back to the previous layout if in the named layout.
2401#: Useful to temporarily "zoom" the active window by switching to the
2402#: stack layout::
2403
2404#: map ctrl+alt+z toggle_layout stack
2405#: }}}
2406
2407#: Font sizes {{{
2408
2409#: You can change the font size for all top-level kitty OS windows at
2410#: a time or only the current one.
2411
2412#: Increase font size
2413
2414# map kitty_mod+equal change_font_size all +2.0
2415# map kitty_mod+plus change_font_size all +2.0
2416# map kitty_mod+kp_add change_font_size all +2.0
2417# map cmd+plus change_font_size all +2.0
2418# map cmd+equal change_font_size all +2.0
2419# map shift+cmd+equal change_font_size all +2.0
2420
2421#: Decrease font size
2422
2423# map kitty_mod+minus change_font_size all -2.0
2424# map kitty_mod+kp_subtract change_font_size all -2.0
2425# map cmd+minus change_font_size all -2.0
2426# map shift+cmd+minus change_font_size all -2.0
2427
2428#: Reset font size
2429
2430# map kitty_mod+backspace change_font_size all 0
2431# map cmd+0 change_font_size all 0
2432
2433
2434#: To setup shortcuts for specific font sizes::
2435
2436#: map kitty_mod+f6 change_font_size all 10.0
2437
2438#: To setup shortcuts to change only the current OS window's font
2439#: size::
2440
2441#: map kitty_mod+f6 change_font_size current 10.0
2442#: }}}
2443
2444#: Select and act on visible text {{{
2445
2446#: Use the hints kitten to select text and either pass it to an
2447#: external program or insert it into the terminal or copy it to the
2448#: clipboard.
2449
2450#: Open URL
2451
2452# map kitty_mod+e open_url_with_hints
2453
2454#:: Open a currently visible URL using the keyboard. The program used
2455#:: to open the URL is specified in open_url_with.
2456
2457#: Insert selected path
2458
2459# map kitty_mod+p>f kitten hints --type path --program -
2460
2461#:: Select a path/filename and insert it into the terminal. Useful,
2462#:: for instance to run git commands on a filename output from a
2463#:: previous git command.
2464
2465#: Open selected path
2466
2467# map kitty_mod+p>shift+f kitten hints --type path
2468
2469#:: Select a path/filename and open it with the default open program.
2470
2471#: Insert selected line
2472
2473# map kitty_mod+p>l kitten hints --type line --program -
2474
2475#:: Select a line of text and insert it into the terminal. Useful for
2476#:: the output of things like: `ls -1`.
2477
2478#: Insert selected word
2479
2480# map kitty_mod+p>w kitten hints --type word --program -
2481
2482#:: Select words and insert into terminal.
2483
2484#: Insert selected hash
2485
2486# map kitty_mod+p>h kitten hints --type hash --program -
2487
2488#:: Select something that looks like a hash and insert it into the
2489#:: terminal. Useful with git, which uses SHA1 hashes to identify
2490#:: commits.
2491
2492#: Open the selected file at the selected line
2493
2494# map kitty_mod+p>n kitten hints --type linenum
2495
2496#:: Select something that looks like filename:linenum and open it in
2497#:: your default editor at the specified line number.
2498
2499#: Open the selected hyperlink
2500
2501# map kitty_mod+p>y kitten hints --type hyperlink
2502
2503#:: Select a hyperlink (i.e. a URL that has been marked as such by
2504#:: the terminal program, for example, by `ls --hyperlink=auto`).
2505
2506
2507#: The hints kitten has many more modes of operation that you can map
2508#: to different shortcuts. For a full description see hints kitten
2509#: <https://sw.kovidgoyal.net/kitty/kittens/hints/>.
2510#: }}}
2511
2512#: Miscellaneous {{{
2513
2514#: Show documentation
2515
2516# map kitty_mod+f1 show_kitty_doc overview
2517
2518#: Toggle fullscreen
2519
2520# map kitty_mod+f11 toggle_fullscreen
2521# map ctrl+cmd+f toggle_fullscreen
2522
2523#: Toggle maximized
2524
2525# map kitty_mod+f10 toggle_maximized
2526
2527#: Toggle macOS secure keyboard entry
2528
2529# map opt+cmd+s toggle_macos_secure_keyboard_entry
2530
2531#: Unicode input
2532
2533# map kitty_mod+u kitten unicode_input
2534# map ctrl+cmd+space kitten unicode_input
2535
2536#: Edit config file
2537
2538# map kitty_mod+f2 edit_config_file
2539# map cmd+, edit_config_file
2540
2541#: Open the kitty command shell
2542
2543# map kitty_mod+escape kitty_shell window
2544
2545#:: Open the kitty shell in a new window / tab / overlay / os_window
2546#:: to control kitty using commands.
2547
2548#: Increase background opacity
2549
2550# map kitty_mod+a>m set_background_opacity +0.1
2551
2552#: Decrease background opacity
2553
2554# map kitty_mod+a>l set_background_opacity -0.1
2555
2556#: Make background fully opaque
2557
2558# map kitty_mod+a>1 set_background_opacity 1
2559
2560#: Reset background opacity
2561
2562# map kitty_mod+a>d set_background_opacity default
2563
2564#: Reset the terminal
2565
2566# map kitty_mod+delete clear_terminal reset active
2567# map opt+cmd+r clear_terminal reset active
2568
2569#:: You can create shortcuts to clear/reset the terminal. For
2570#:: example::
2571
2572#:: # Reset the terminal
2573#:: map f1 clear_terminal reset active
2574#:: # Clear the terminal screen by erasing all contents
2575#:: map f1 clear_terminal clear active
2576#:: # Clear the terminal scrollback by erasing it
2577#:: map f1 clear_terminal scrollback active
2578#:: # Scroll the contents of the screen into the scrollback
2579#:: map f1 clear_terminal scroll active
2580#:: # Clear everything on screen up to the line with the cursor or the start of the current prompt (needs shell integration)
2581#:: map f1 clear_terminal to_cursor active
2582#:: # Same as above except cleared lines are moved into scrollback
2583#:: map f1 clear_terminal to_cursor_scroll active
2584
2585#:: If you want to operate on all kitty windows instead of just the
2586#:: current one, use all instead of active.
2587
2588#:: Some useful functions that can be defined in the shell rc files
2589#:: to perform various kinds of clearing of the current window:
2590
2591#:: .. code-block:: sh
2592
2593#:: clear-only-screen() {
2594#:: printf "\e[H\e[2J"
2595#:: }
2596
2597#:: clear-screen-and-scrollback() {
2598#:: printf "\e[H\e[3J"
2599#:: }
2600
2601#:: clear-screen-saving-contents-in-scrollback() {
2602#:: printf "\e[H\e[22J"
2603#:: }
2604
2605#:: For instance, using these escape codes, it is possible to remap
2606#:: Ctrl+L to both scroll the current screen contents into the
2607#:: scrollback buffer and clear the screen, instead of just clearing
2608#:: the screen. For ZSH, in ~/.zshrc, add:
2609
2610#:: .. code-block:: zsh
2611
2612#:: ctrl_l() {
2613#:: builtin print -rn -- $'\r\e[0J\e[H\e[22J' >"$TTY"
2614#:: builtin zle .reset-prompt
2615#:: builtin zle -R
2616#:: }
2617#:: zle -N ctrl_l
2618#:: bindkey '^l' ctrl_l
2619
2620#:: Alternatively, you can just add map ctrl+l clear_terminal
2621#:: to_cursor_scroll active to kitty.conf which works with no changes
2622#:: to the shell rc files, but only clears up to the prompt, it does
2623#:: not clear any text at the prompt itself.
2624
2625#: Clear to start
2626
2627# map cmd+k clear_terminal to_cursor active
2628
2629#: Clear scrollback
2630
2631# map option+cmd+k clear_terminal scrollback active
2632
2633#: Clear screen
2634
2635# map cmd+ctrl+l clear_terminal to_cursor_scroll active
2636
2637#: Reload kitty.conf
2638
2639# map kitty_mod+f5 load_config_file
2640# map ctrl+cmd+, load_config_file
2641
2642#:: Reload kitty.conf, applying any changes since the last time it
2643#:: was loaded. Note that a handful of options cannot be dynamically
2644#:: changed and require a full restart of kitty. Particularly, when
2645#:: changing shortcuts for actions located on the macOS global menu
2646#:: bar, a full restart is needed. You can also map a keybinding to
2647#:: load a different config file, for example::
2648
2649#:: map f5 load_config /path/to/alternative/kitty.conf
2650
2651#:: Note that all options from the original kitty.conf are discarded,
2652#:: in other words the new configuration *replace* the old ones.
2653
2654#: Debug kitty configuration
2655
2656# map kitty_mod+f6 debug_config
2657# map opt+cmd+, debug_config
2658
2659#:: Show details about exactly what configuration kitty is running
2660#:: with and its host environment. Useful for debugging issues.
2661
2662#: Send arbitrary text on key presses
2663
2664#:: E.g. map ctrl+shift+alt+h send_text all Hello World
2665
2666#:: You can tell kitty to send arbitrary (UTF-8) encoded text to the
2667#:: client program when pressing specified shortcut keys. For
2668#:: example::
2669
2670#:: map ctrl+alt+a send_text all Special text
2671
2672#:: This will send "Special text" when you press the Ctrl+Alt+A key
2673#:: combination. The text to be sent decodes ANSI C escapes
2674#:: <https://www.gnu.org/software/bash/manual/html_node/ANSI_002dC-
2675#:: Quoting.html> so you can use escapes like \e to send control
2676#:: codes or \u21fb to send Unicode characters (or you can just input
2677#:: the Unicode characters directly as UTF-8 text). You can use
2678#:: `kitten show-key` to get the key escape codes you want to
2679#:: emulate.
2680
2681#:: The first argument to send_text is the keyboard modes in which to
2682#:: activate the shortcut. The possible values are normal,
2683#:: application, kitty or a comma separated combination of them. The
2684#:: modes normal and application refer to the DECCKM cursor key mode
2685#:: for terminals, and kitty refers to the kitty extended keyboard
2686#:: protocol. The special value all means all of them.
2687
2688#:: Some more examples::
2689
2690#:: # Output a word and move the cursor to the start of the line (like typing and pressing Home)
2691#:: map ctrl+alt+a send_text normal Word\e[H
2692#:: map ctrl+alt+a send_text application Word\eOH
2693#:: # Run a command at a shell prompt (like typing the command and pressing Enter)
2694#:: map ctrl+alt+a send_text normal,application some command with arguments\r
2695
2696#: Open kitty Website
2697
2698# map shift+cmd+/ open_url https://sw.kovidgoyal.net/kitty/
2699
2700#: Hide macOS kitty application
2701
2702# map cmd+h hide_macos_app
2703
2704#: Hide macOS other applications
2705
2706# map opt+cmd+h hide_macos_other_apps
2707
2708#: Minimize macOS window
2709
2710# map cmd+m minimize_macos_window
2711
2712#: Quit kitty
2713
2714# map cmd+q quit
2715
2716#: }}}
2717
2718#: }}}