Matching windows#
When matching windows, match specifications are of the form: field:query.
Where field can be one of: id
, title
, pid
, cwd
, cmdline
, num
,
env
, var
, state
, neighbor
, and recent
.
query is the expression to match. Expressions can be either a number or a regular expression, and can be
combined using Boolean operators.
The special value all
matches all windows.
For numeric fields: id
, pid
, num
and recent
, the expression is interpreted as
a number, not a regular expression. Negative values for id
match from the highest id number down, in particular,
-1 is the most recently created window.
The field num
refers to the window position in the current tab, starting from zero and counting clockwise (this
is the same as the order in which the windows are reported by the kitten @ ls command).
The window id of the current window is available as the KITTY_WINDOW_ID
environment variable.
The field recent
refers to recently active windows in the currently active tab, with zero being the currently
active window, one being the previously active window and so on.
The field neighbor
refers to a neighbor of the active window in the specified direction, which can be:
left
, right
, top
or bottom
.
When using the env
field to match on environment variables, you can specify only the environment variable name
or a name and value, for example, env:MY_ENV_VAR=2
.
Similarly, the var
field matches on user variables set on the window. You can specify name or name and value
as with the env
field.
The field state
matches on the state of the window. Supported states
are: active
, focused
, needs_attention
,
parent_active
, parent_focused
, self
,
overlay_parent
. Active windows are the windows that are active in
their parent tab. There is only one focused window and it is the window to
which keyboard events are delivered. If no window is focused, the last focused
window is matched. The value self
matches the window in which the
remote control command is run. The value overlay_parent
matches the
window that is under the self
window, when the self window is an
overlay.
Note that you can use the kitten @ ls command to get a list of windows.
Matching tabs#
When matching tabs, match specifications are of the form: field:query.
Where field can be one of: id
, index
, title
, window_id
, window_title
,
pid
, cwd
, cmdline
env
, var
, state
and recent
.
query is the expression to match. Expressions can be either a number or a regular expression, and can be
combined using Boolean operators.
The special value all
matches all tabs.
For numeric fields: id
, index
, window_id
, pid
and recent
, the
expression is interpreted as a number, not a regular expression. Negative values for id
/window_id
match
from the highest id number down, in particular, -1 is the most recently created tab/window.
When using title
or id
, first a matching tab is looked for, and if not found a matching window is looked
for, and the tab for that window is used.
You can also use window_id
and window_title
to match the tab that contains the window with the specified
id or title.
The index
number is used to match the nth tab in the currently active OS window.
The recent
number matches recently active tabs in the currently active OS window, with zero being the currently
active tab, one the previously active tab and so on.
When using the env
field to match on environment variables, you can specify only the environment variable name
or a name and value, for example, env:MY_ENV_VAR=2
. Tabs containing any window with the specified environment
variables are matched. Similarly, var
matches tabs containing any window with the specified user variable.
The field state
matches on the state of the tab. Supported states are:
active
, focused
, needs_attention
, parent_active
and parent_focused
.
Active tabs are the tabs that are active in their parent OS window. There is only one focused tab
and it is the tab to which keyboard events are delivered. If no tab is focused, the last focused tab is matched.
Note that you can use the kitten @ ls command to get a list of tabs.