Keyboard layouts and macOS
Keyboard layouts and macOS: part of the Keybindings of TUIOS.
This page is one part of docs/KEYBINDINGS.md of the tuios repository. The Keybindings page lists every part.
Other keyboard layouts
Bindings work with layouts for non-Latin scripts, such as Cyrillic, Greek,
Hebrew or Arabic. When no binding matches the character a key types, tuios uses
the key at the same position on a US layout. With a Ukrainian layout, the key
that types ш is the US i key, so ctrl+b then that key opens the agents view. A
binding on the typed character wins, so you can still bind ш yourself. Text
that you type into a pane, a rename or a search stays the character that you
typed.
Latin layouts, such as AZERTY, QWERTZ or Dvorak, use the letters on their keys.
A letter or a ctrl chord means the key that it types, not the US key at its
position. On Dvorak, the key that types b is the US n key, and ctrl with
it is ctrl+b, the leader. The showkeys strip, the binding recorder and a
tape spell the chord the same way. A Latin letter with no binding does nothing.
This needs a terminal that sends the US-layout key through the Kitty keyboard protocol: Ghostty, kitty, WezTerm or foot. Other terminals send only the typed character. With those, switch to a Latin layout for tuios commands.
In window mode tuios tells the terminal to send every key as a code. tuios
resets this when it stops. If tuios cannot stop correctly, the terminal can
stay in this mode. This occurs when you use kill -9 on tuios, or when an ssh
connection drops. The shell then shows codes such as [97u when you type. To
reset the terminal, run this command or close the tab:
printf '\033[=0;1u'Shifted digits and AZERTY
On a US keyboard & is shift+7. Some terminals send the chord and others send
the character. By default, a binding on opt+shift+7 therefore also matches
opt+&, and a binding on ! also matches shift+1. These US aliases apply
only when no binding names the key itself. A binding that you write for a key
always wins over an alias.
On other layouts these keys are in other places. On a French Mac, & is the
unshifted 1 key and the digits need Shift. tuios turns off the US aliases for a
key when the terminal reports that the key is not where a US layout has it.
Terminals that send this through the Kitty keyboard protocol include Ghostty,
kitty, WezTerm and foot. Other terminals do not report the layout. To turn off
the US aliases for every key, set this:
[keybindings]
keyboard_layout = "other" # the default is "us"tuios keybinds explain opt+& shows a binding that the key runs through a US
alias.
A recipe for French AZERTY on macOS
Set the left Option key to send Alt. In iTerm2 this is "Esc+". In WezTerm it
is send_composed_key_when_left_alt_is_pressed = false. Then:
- Option and Shift with a number key types the digit. The default
opt+1toopt+9switch workspaces with it. - The default
opt+shift+1toopt+shift+9need Shift and a digit together, which AZERTY cannot type. Bind the move to the unshifted keys:
[keybindings]
keyboard_layout = "other"
[keybindings.workspaces]
move_and_follow_1 = ["opt+&"]
move_and_follow_2 = ["opt+é"]
move_and_follow_3 = ['opt+"']
move_and_follow_4 = ["opt+'"]
move_and_follow_5 = ["opt+("]
move_and_follow_6 = ["opt+§"]
move_and_follow_7 = ["opt+è"]
move_and_follow_8 = ["opt+!"]
move_and_follow_9 = ["opt+ç"]To type [ ] { } | with Option, set the right Option key to compose. See
One Option key for typing. With
keyboard_layout = "other", tuios sends those characters to the pane.
French AZERTY on macOS
Set the left Option key to send Alt. In iTerm2 this is "Esc+". In WezTerm it is send_composed_key_when_left_alt_is_pressed = false. Then:
- Option and Shift with a number key types the digit. The default
opt+1toopt+9switch workspaces with it. - The default
opt+shift+1toopt+shift+9need Shift and a digit together, which AZERTY cannot type. Bind the move to the unshifted keys:
[keybindings]
keyboard_layout = "other"
[keybindings.workspaces]
move_and_follow_1 = ["opt+&"]
move_and_follow_2 = ["opt+é"]
move_and_follow_3 = ['opt+"']
move_and_follow_4 = ["opt+'"]
move_and_follow_5 = ["opt+("]
move_and_follow_6 = ["opt+§"]
move_and_follow_7 = ["opt+è"]
move_and_follow_8 = ["opt+!"]
move_and_follow_9 = ["opt+ç"]To type [ ] { } | with Option, set the right Option key to compose. See One Option key for typing. With keyboard_layout = "other", TUIOS sends those characters to the pane.
A character that Option types, after the leader
On a German Mac layout, | is Option+7 and \ is Option+Shift+7. After the leader, Ghostty and other terminals with the Kitty keyboard protocol report that key as Alt+7 with the text |. TUIOS now tries that character too, so Ctrl+B then Option+7 runs the binding on |, the split.
- TUIOS tries the character last, when the chord is Alt or Alt+Shift and the character is printable ASCII that the key does not give by itself or with Shift on a US layout.
- A binding on the chord still wins. Option+7 still goes to workspace 7 in window mode.
Characters typed with Option
Some layouts type ASCII characters with Option. On a German Mac, | is
Option and 7, \ is Option, Shift and 7, and @ is Option and L. While tuios
reads keys itself (window mode, after the leader, an overlay), Ghostty sends
such a key as the chord and the character: Option and 7 is opt+7 with the
text |. A binding on the chord runs first, so opt+7 still goes to
workspace 7 in window mode. When no binding has the chord, the binding on the
character runs, so ctrl+b then Option and 7 splits the pane as ctrl+b |
does. In a pane the character is text, as before.
Keys sent to a pane
In terminal mode, tuios sends these keys to the program in the pane:
- The keypad keys, with Num Lock on or off. Keypad
Entersends Enter. Begin, the centre key of the keypad with Num Lock off.- F13 and higher. A program on the legacy encoding gets them in the form xterm sends.
Insert,Delete,PageUpandPageDownwith their modifiers.ctrl+Deletestaysctrl+Delete.
A program on the Kitty keyboard protocol gets each key with the number the protocol gives it. A key the protocol has no number for goes in its legacy form. Caps Lock, Num Lock and a modifier key pressed alone reach that program only when it asks for every key.
Shift+Up, Shift+Down, Shift+PageUp and Shift+PageDown
shift+up and shift+down scroll the pane into its history. They do this
only when all of these are true:
- The program is on the main screen.
- The program did not turn on a mouse mode.
shift+pgup and shift+pgdown follow the same rules, but scroll one visible
pane page at a time. In other panes, tuios sends the keys to the program.
Programs that use the full screen, such as nvim, less and htop, get them. When
the pane is in copy mode, the keys scroll. This is the same rule as the mouse
wheel, and the same rule as kitty.
To change the keys, set terminal_scroll_up, terminal_scroll_down,
terminal_scroll_page_up and terminal_scroll_page_down in
[keybindings.terminal_mode].
macOS
Option is a compose key on macOS unless the terminal is told otherwise. An Option chord then arrives as a character, not as Alt. Terminal.app and iTerm2 work like this until you change their settings.
The same character can come from two keys. On a US keyboard, Option+3 types
£. On a UK keyboard, Shift+3 types £. tuios reads the keyboard layout of
the Mac when it starts:
- On a US or ABC layout, tuios runs the
opt+binding for the character. Option+3 types£and switches to workspace 3. - On any other layout, the character goes to the pane. tuios also does this when it cannot read the layout.
If you change the layout while tuios runs, tuios reads it again when such a character arrives and the last read is more than 30 seconds old. The new layout applies from the next key. A tuios that serves SSH or web clients from a Mac uses the layout of that Mac.
keyboard_layout overrides the layout that tuios reads. With
keyboard_layout = "us", tuios runs the binding. With
keyboard_layout = "other", the character goes to the pane.
To use the opt+ bindings on every layout, set your terminal to send Option
as Alt. See The fix.
Some terminals, such as Ghostty and kitty, send the character and also report
Alt. tuios then runs the opt+ binding on every layout. For example,
Option+8 types • and switches to workspace 8.
To set the behaviour yourself, use option_glyphs:
[keybindings]
option_glyphs = "auto" # auto, alt, bind, typeautouses the layout of the Mac, as above. This is the default.altruns the binding only when the terminal reports Alt.bindalways runs the binding. Use it only on a US keyboard.typealways sends the character to the pane. Use it if you type characters such as#,•or{with Option.
Two kinds of chord cannot be read:
- Dead keys. Option+e, i, n, u and backtick emit nothing at all until a
second key ends the composition.
alt+nis bound to "next pane" in terminal mode, and on a stock macOS terminal it takes two presses. - Rewritten chords. Option+Left and Option+Right are sent as the readline
word motions,
ESC bandESC f. Nothing in what arrives says an arrow key was pressed. Ghostty ships keybinds that do this, and they win even with Option-as-Alt turned on.
Command chords never reach a program inside a terminal at all; macOS routes them to the menu bar.
The fix
Turn on your terminal's Option-as-Alt setting:
| Terminal | Setting |
|---|---|
| Ghostty | macos-option-as-alt = true in ~/.config/ghostty/config |
| Terminal.app | Settings, Profiles, Keyboard, tick "Use Option as Meta Key" |
| iTerm2 | Settings, Profiles, Keys, set Left Option key to "Esc+" |
| kitty | macos_option_as_alt yes in ~/.config/kitty/kitty.conf |
| WezTerm | send_composed_key_when_left_alt_is_pressed = false |
| Alacritty | option_as_alt = "Both" under [window] |
| VS Code | turn on terminal.integrated.macOptionIsMeta |
| Tern | set option_as_alt in Tern's settings.json |
Ghostty needs two more lines, because its own keybinds rewrite the arrows before any encoding happens:
keybind = alt+left=unbind
keybind = alt+right=unbindtuios shows this on screen one time, when an Option chord arrives as a character and not as Alt. On a layout other than US or ABC it does not show it, because the character can be text.
One Option key for typing
Some terminals let you set the two Option keys differently. Use the left Option
key for tuios and the right Option key to type characters such as #, • or
{. In WezTerm:
config.send_composed_key_when_left_alt_is_pressed = false
config.send_composed_key_when_right_alt_is_pressed = trueIn iTerm2, set Left Option key to "Esc+" and Right Option key to "Normal". Then set this, so that the right Option key types characters into the pane:
[keybindings]
option_glyphs = "type"The left Option key sends Alt and runs tuios bindings. The right Option key types characters into the pane.
What works without changing anything
The prefix. Every navigation command has a prefix binding, and the prefix is an
ordinary ctrl chord that no terminal interferes with:
| Keys | What it does |
|---|---|
ctrl+b then an arrow | Focus the pane in that direction |
ctrl+b n / ctrl+b p | Next and previous pane |
ctrl+b ( / ctrl+b ) | Previous and next session |
ctrl+b K / ctrl+b J | Previous and next agent pane |
ctrl+b a | Launcher |
ctrl+b 0 to ctrl+b 9 | Jump to a pane |
The prefix stays armed for half a second after a command worth repeating, so
ctrl+b then left left left walks three panes on one prefix press. This is
tmux's repeat-time, and appearance.prefix_repeat_time changes it. Zero
turns it off.
These actions repeat when you bind them under the leader: the focus moves,
next_window, prev_window, next_workspace, prev_workspace, the
resize_pane_* steps, the resize_master_* and resize_height_* steps, and
the scroll_* moves and width cycle. ctrl+b o and ctrl+b O repeat too.
Other actions run once.
keybindings.repeat sets your own list, as tmux bind -r does. The list
replaces the default list. An empty list turns repeat off:
[keybindings]
# n and p switch workspaces once, so the next n or p you type reaches the shell
repeat = ["terminal_focus_left", "terminal_focus_right", "focus_up",
"focus_down"]
[keybindings.prefix_mode]
next_workspace = ["n"]
prev_workspace = ["p"]An action in the list repeats only when a key runs it after the leader. tuios warns about an entry with no such key, and about a misspelt action.
With keybindings.lock on, there is no repeat window in terminal mode. A
repeatable action keeps its menu open until you press esc, with no time
limit. The open menu takes only repeatable keys. Any other key goes to the
pane, and tuios locks again. See Lock mode.
Workspace switching on opt+1 to opt+9 works with no configuration on a
US or ABC keyboard layout. It also works in a terminal that reports Alt with
the character, such as Ghostty and kitty. On other layouts in Terminal.app
and iTerm2, Option+1 types its character and does not switch. Set the
terminal to send Option as Alt.
The agents view
The agents view: part of the Keybindings of TUIOS.
Keys by mode
Keys by mode: part of the Keybindings of TUIOS.
tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.