Launching programs in new windows/tabs¶
kitty has a launch
action that can be used to run arbitrary programs
in new windows/tabs. It can be mapped to user defined shortcuts in kitty.conf.
It is very powerful and allows sending the contents of
the current window to the launched program, as well as many other options.
In the simplest form, you can use it to open a new kitty window running the shell, as shown below:
map f1 launch
To run a different program simply pass the command line as arguments to launch:
map f1 launch vim path/to/some/file
To open a new window with the same working directory as the currently active window:
map f1 launch --cwd=current
To open the new window in a new tab:
map f1 launch --type=tab
To run multiple commands in a shell, use:
map f1 launch sh -c "ls && zsh"
To pass the contents of the current screen and scrollback to the started process:
map f1 launch --stdin-source=@screen_scrollback less
There are many more powerful options, refer to the complete list below.
The piping environment¶
When using launch --stdin-source
, the program to which the data is
piped has a special environment variable declared, KITTY_PIPE_DATA
whose
contents are:
KITTY_PIPE_DATA={scrolled_by}:{cursor_x},{cursor_y}:{lines},{columns}
where scrolled_by
is the number of lines kitty is currently scrolled by,
cursor_(x|y)
is the position of the cursor on the screen with (1,1)
being the top left corner and {lines},{columns}
being the number of rows
and columns of the screen.
Special arguments¶
There are a few special placeholder arguments that can be specified as part of the command line:
@selection
replaced by the currently selected text
@active-kitty-window-id
replaced by the id of the currently active kitty window
@line-count
replaced by the number of lines in STDIN. Only present when passing some data to STDIN
@input-line-number
replaced the number of lines a pager should scroll to match the current scroll position in kitty. See
scrollback_pager
for details@scrolled-by
replaced by the number of lines kitty is currently scrolled by
@cursor-x
replaced by the current cursor x position with 1 being the leftmost cell
@cursor-y
replaced by the current cursor y position with 1 being the topmost cell
For example:
map f1 launch my-program @active-kitty-window-id
Watching launched windows¶
The launch --watcher
option allows you to specify python functions
that will be called at specific events, such as when the window is resized or
closed. Simply specify the path to a python module that specifies callback
functions for the events you are interested in, for example:
def on_resize(boss, window, data):
# Here data will contain old_geometry and new_geometry
def on_focus_change(boss, window, data):
# Here data kill contain focused
def on_close(boss, window, data):
# called when window is closed, typically when the program running in
# it exits.
Every callback is passed a reference to the global Boss
object as well as
the Window
object the action is occurring on. The data
object is
mapping that contains event dependent data. Some useful methods and attributes
for the Window
object are: as_text(as_ans=False, add_history=False,
add_wrap_markers=False, alternate_screen=False)
with which you can get the
contents of the window and its scrollback buffer. Similarly,
window.child.pid
is the PID of the processes that was launched
in the window and window.id
is the internal kitty id
of the
window.
Finding executables¶
When you specify a command to run as just a name rather than an absolute path,
it is searched for in the system-wide PATH
environment variable. Note that
this may not be the value of PATH
inside a shell, as shell startup scripts
often change the value of this variable. If it is not found there, then a
system specific list of default paths is searched. If it is still not found,
then your shell is run and the value of PATH
inside the shell is used.
Syntax reference¶
launch [options] [program-to-run ...]
Launch an arbitrary program in a new kitty window/tab. Note that
if you specify a program-to-run you can use the special placeholder
@selection
which will be replaced by the current selection.
Options¶
-
--title
<WINDOW_TITLE>
,
--window-title
<WINDOW_TITLE>
¶ The title to set for the new window. By default, title is controlled by the child process.
-
--tab-title
<TAB_TITLE>
¶ The title for the new tab if launching in a new tab. By default, the title of the active window in the tab is used as the tab title.
-
--type
<TYPE>
¶ Where to launch the child process, in a new kitty window in the current tab, a new tab, or a new OS window or an overlay over the current window. Note that if the current window already has an overlay, then it will open a new window. The value of background means the process will be run in the background. The values clipboard and primary are meant to work with
launch --stdin-source
to copy data to the system clipboard or primary selection. Default:window
Choices:background, clipboard, os-window, overlay, primary, tab, window
-
--keep-focus
¶
Keep the focus on the currently active window instead of switching to the newly opened window.
-
--cwd
<CWD>
¶ The working directory for the newly launched child. Use the special value
current
to use the working directory of the currently active window.
-
--env
<ENV>
¶ Environment variables to set in the child process. Can be specified multiple times to set different environment variables. Syntax: name=value.
-
--copy-colors
¶
Set the colors of the newly created window to be the same as the colors in the currently active window.
-
--copy-cmdline
¶
Ignore any specified command line and instead use the command line from the currently active window.
-
--copy-env
¶
Copy the environment variables from the currently active window into the newly launched child process. Note that most shells only set environment variables for child processes, so this will only copy the environment variables that the shell process itself has not the environment variables child processes inside the shell see. To copy that enviroment, use the kitty remote control feature with
kitty @launch --copy-env
.
-
--location
<LOCATION>
¶ Where to place the newly created window when it is added to a tab which already has existing windows in it.
after
andbefore
place the new window before or after the active window.neighbor
is a synonym forafter
. Also applies to creating a new tab, where the value ofafter
will cause the new tab to be placed next to the current tab instead of at the end. The values ofvsplit
andhsplit
are only used by thesplits
layout and control if the new window is placed in a vertical or horizontal split with the currently active window. The default is to place the window in a layout dependent manner, typically, after the currently active window. Default:default
Choices:after, before, default, first, hsplit, last, neighbor, vsplit
-
--allow-remote-control
¶
Programs running in this window can control kitty (if remote control is enabled). Note that any program with the right level of permissions can still write to the pipes of any other program on the same computer and therefore can control kitty. It can, however, be useful to block programs running on other computers (for example, over ssh) or as other users.
-
--stdin-source
<STDIN_SOURCE>
¶ Pass the screen contents as
STDIN
to the child process.@selection
is the currently selected text.@screen
is the contents of the currently active window.@screen_scrollback
is the same as@screen
, but includes the scrollback buffer as well.@alternate
is the secondary screen of the current active window. For example if you run a full screen terminal application, the secondary screen will be the screen you return to when quitting the application. Default:none
Choices:@alternate, @alternate_scrollback, @screen, @screen_scrollback, @selection, none
-
--stdin-add-formatting
¶
When using
launch --stdin-source
add formatting escape codes, without this only plain text will be sent.
-
--stdin-add-line-wrap-markers
¶
When using
launch --stdin-source
add a carriage return at every line wrap location (where long lines are wrapped at screen edges). This is useful if you want to pipe to program that wants to duplicate the screen layout of the screen.
-
--marker
<MARKER>
¶ Create a marker that highlights text in the newly created window. The syntax is the same as for the
toggle_marker
map action (see Marks).
-
--os-window-class
<OS_WINDOW_CLASS>
¶ Set the WM_CLASS property on X11 and the application id property on Wayland for the newly created OS Window when using
launch --type
=os-window
. Defaults to whatever is used by the parent kitty process, which in turn defaults tokitty
.
-
--os-window-name
<OS_WINDOW_NAME>
¶ Set the WM_NAME property on X11 for the newly created OS Window when using
launch --type
=os-window
. Defaults tolaunch --os-window-class
.
-
--color
<COLOR>
¶ Change colors in the newly launched window. You can either specify a path to a .conf file with the same syntax as kitty.conf to read the colors from, or specify them individually, for example:
--color background=white
--color foreground=red
-
--watcher
<WATCHER>
,
-w
<WATCHER>
¶ Path to a python file. Appropriately named functions in this file will be called for various events, such as when the window is resized, focused or closed. See the section on watchers in the launch command documentation Launching programs in new windows/tabs. Relative paths are resolved relative to the kitty config directory.