Dedicated action to send a keypress when another key is pressed

[00-kat]

Currently, this is possible through text:, esc: and csi:, but anyone who wants to do it needs to know how keypresses are encoded to the terminal. I've detailed this below for anyone who finds this and wants to bind a key right now, and to add emphasis on how this is not a particularly easy task without external tools or experience working with terminal emulators:

Click or tap to expand a somewhat complete guide on how to encoding your keypresses.

• key (where key has no modifiers) is text:key. That is:

  • a is text:a, b is text:b, etc.
  • A is text:A, B is text:B, etc.
  • 1 is text:1, 2 is text:2, etc.
  • ! is text:!, @ is text:@, etc.
  • space is text: ; don't forget to wrap everything with double-quotes!
    • That is:

      keybind = "ctrl+w=text: "

  • è is text:è, € is text:€, й is text:й, 国 is text:国, ∞ is text:∞ (if you somehow have an infinity key), etc. Don't forget to ensure that your Ghostty configuration file is in UTF-8¹², so that the sent text is in UTF-8 too³!

• ctrl+a is text:\x01, ctrl+b is text:\x02, etc. This is in hexadecimal (base 16), so ctrl+z is text:\x1a and not text:\x26.

  Quick primer on hexadecimal numbers…

  • There are sixteen digits, $0\textendash9$ followed by $\mathrm{A}\textendash\mathrm{F}$.

  • $\mathrm{A}$ is $10$, $\mathrm{B}$ is $11$, etc. This means that the number after $9$ is $\mathrm{A}$, not $10$.

  • The number after $\mathrm{F}$ is $10$. $10$ is 16 in decimal.

  • The hexadecimal number $\mathrm{1A3F}$ is 6719 in decimal, since $\left( \mathrm{F}_{16} \times 16_{10}^{0} \right) + \left( 3_{16} \times 16_{10}^{1} \right) + \left( \mathrm{A}_{16} \times 16_{10}^{2} \right) + \left( 1_{16} \times 16_{10}^{3} \right) = \left( 15_{10} \right) + \left( 3_{10} \times 16_{10}^{1} \right) + \left( 10_{10} \times 16_{10}^{2} \right) + \left( 1_{10} \times 16_{10}^{2} \right) = 6719_{10}\mathrm{.}$ The same applies for any other hexadecimal number, $\mathrm{1A3F}$ was just an example.

    • $17_{10}$ represents “the number $17$ in base 10”, and $\mathrm{3F}_{16}$ represents “the number $\mathrm{3F}$ in base 16”.
    • It is also common to see hexadecimal numbers represented as 0x3F.

  • Here's a trick to convert a decimal number to hexadecimal:

    1. Divide the number by 16, and record the quotient (in decimal) and the remainder (in hexadecimal). Throw away any anything after the decimal point in the quotient.
    2. Write down the remainder on a new line, or a piece of paper, or something. Leave enough space on the left of the number if you are using a sheet of paper.
    3. Repeat step one with the quotient as the new number.
    4. Write down the new remainder to the left of the numbers you have previously noted down.
    5. Repeat steps three and four until you are left with a quotient of zero.
    6. The number you have written down is the converted number in hexadecimal.

    Since this is tedious to do by hand, you could use something like Python (hex(1234) to convert 1234 to hexadecimal, and 0x3F1A to convert 3F1A to decimal) or one of the many calculators available online. Here's a table of numbers from 1 to 26 converted for the lazy:

    Table of decimal numbers from 1 to 26 as well as their hexadecimal representations.

    Decimal	Hexadecimal	Decimal	Hexadecimal
    $1$	$1$	$14$	$\mathrm{E}$
    $2$	$2$	$15$	$\mathrm{F}$
    $3$	$3$	$16$	$10$
    $4$	$4$	$17$	$11$
    $5$	$5$	$18$	$12$
    $6$	$6$	$19$	$13$
    $7$	$7$	$20$	$14$
    $8$	$8$	$21$	$15$
    $9$	$9$	$22$	$16$
    $10$	$\mathrm{A}$	$23$	$17$
    $11$	$\mathrm{B}$	$24$	$18$
    $12$	$\mathrm{C}$	$25$	$19$
    $13$	$\mathrm{D}$	$26$	$\mathrm{1A}$

• ctrl+shift+key is not possible with the legacy encoding without Fixterms.

• ctrl+non-ASCII character is not possible with the legacy encoding, even when using Fixterms.

• alt+key for any key is esc:X where X is the encoded form of key. Some examples:

  • alt+a is esc:a.
  • alt+ctrl+a is esc:\x01.

• alt+non-ASCII character does not seem to be possible with the legacy encoding, even when using Fixterms, based on my experimentation.

• I can't discern any pattern in how ctrl+number is encoded, though it may be related to their encoding in ASCII.

• ctrl+special character cannot be encoded in the legacy encoding without Fixterms.

• up is csi:A, down is csi:B, right is csi:C, left is csi:D, home is csi:H and end is csi:F.

  • DECCKM does change the encoding of arrow keys though, and there's no real way to detect that from the configuration file.

• backspace and delete is particularly problematic as there are many common encodings for it, all with varying levels of portability, including ASCII DEL, ASCII BS (backspace, also the same as ctrl+h), an escape sequence, and not sending a keypress but instead just clearing the cell directly. See this well-written article about it for more information. Ghostty uses text:\x7f (ASCII DEL) for backspace and csi:3~ (escape sequence) for delete.

• Without Fixterms or the Kitty keyboard protocol, some special characters may conflict with the encoding of ctrl+key. Some notable ones are that ctrl+[ is the same as esc, ctrl+m is the same as return, and ctrl+i is the same as tab. However, Ghostty implements Fixterms so this isn't a problem unless you want those keys to be conflicted (for example, if you press ctrl+[ because esc is hard for you to reach). This fact can also be used to send some special keys such as tab and esc too, for example if you want ctrl+t to send tab for whatever reason.

• The encoding of some other keys can be found at the Fixterms specification and the Kitty keyboard protocol specification if you're fluent in terminalese, and applications such as kitten show-key let you press a key to see what it's encoded as (related: `ghostty +show-keys` #5889).

  • Fixterms and the Kitty keyboard protocol were created to fix many of these deficiencies in the legacy encoding detailed above, though it is worth noting that many terminal applications do not support Fixterms and the Kitty keyboard protocol.
  • I'm not sure if there's a specification for the legacy encoding. If there is, bonus points if it cared enough to specify behaviour in the presence of non-ASCII characters (though Unicode didn't exist back when DEC made all of their most popular terminals, so I highly doubt it does).

As one can tell from the large amount of text collapsed above, it's pretty difficult for someone trying out Ghostty to determine the exact sequence they need to remap a key to.

There was some previous discussion on this in the Ghostty Discord server in the Common issues that should be covered on the website? thread. For those who cannot or do not wish to join the Discord server, the conversation is replicated below:

Click or tap here to see the Discord conversation.

kat: Forwarded basically, a is the first letter so it's \x01 when encoded, b is the second letter so \x02, etc.
kat: binding a key to send another key is really unintuitive, and should probably be mentioned in the help
kat: or maybe i should open a feature request for a key keybinding action, but then people will certainly ask for multiple subsequent keypresses, so idk
mitchellh: This is making me think we should make an action for this.
mitchellh: keybind = ctrl+enter=enter
keybind = ctrl+backspace=legacy:backspace
keybind = ctrl+space=kitty:ctrl+space
kat: true
kat: and maybe they can be semicolon separated or something for the people who want to send multiple keys
mitchellh: we're working on a separate proposal that iv'e accepted but havne't figured out the syntax for yet so no issue where keybinds can chain mlutiple actions
mitchellh: so that'll solve that
kat: 👍️
jcollie: hah i was just thinking about chaning keybind actions together but then the parsing started to get gnarly
mitchellh: yeah i bikeshedded it for maybe 30 minutes today and moved on
mitchellh: ill come back to it tmrw i think

ⓘ  Note

The proposal Mitchell mentioned is #3175.

Currently, the only proposals for the syntax are:

• key:, proposed by me:

  keybind = ctrl+k=key:ctrl+c
  keybind = ctrl+j=key:ctrl+shift+j
  keybind = ctrl+k=key:alt+h
  keybind = ctrl+f=key:scroll_lock+ctrl+shift+f22

  This approach reduces the complexity and exposure to jargon for the user, but does not make it clear if a keypress would actually be usable by an application. It also doesn't give the user control over the encoding of their keypress unless they want to switch back to text:/esc:/csi:. It however means that Ghostty can transparently determine the correct encoding depending on whether the terminal application has opted into the Kitty keyboard protocol or not (and also account for DECCKM, though I don't know if any application even uses that).
• legacy: and kitty:, proposed by Mitchell:

  keybind = ctrl+k=legacy:ctrl+c
  keybind = ctrl+j=legacy:ctrl+shift+j
  keybind = ctrl+k=kitty:alt+h
  keybind = ctrl+f=kitty:scroll_lock+ctrl+shift+f22

  This approach makes it clear how a keypress would be encoded, but would be a greater barrier for someone who is not familiar with what the Kitty keyboard protocol is. It also gives the user control over how their key should be encoded, for maximum compatibility with any terminal application the user may be facing. It however means that applications which opt-in to the Kitty keyboard protocol would receive keys in the form of the legacy encoding if the respective keypress is pressed (though I'm not sure if the spec mandates that both should be accepted even when the keyboard protocol is enabled).
• All three of key:, legacy: and kitty:. I am of the opinion that three separate actions is overkill, however.

As mentioned in the Discord conversation, binding a single key to multiple keypresses (e.g. binding ctrl+q to ctrl+x>ctrl+c) would be handled by #3175.

Alternatives to a keybinding action include:

• Do nothing, and hope people can figure it out themselves.
• A page in the documentation about this matter.
• Something like ghostty +show-keys (see also: `ghostty +show-keys` #5889).

Footnotes

1. …except if your locale isn't UTF-8, but that's very uncommon on UNIX-like operating systems these days. ↩

2. …except on Windows, where it has to be in UTF-16. UTF-8 input is wontfix. Thank you Microsoft for your incredibly helpful contributions to society. ↩

3. I'm not sure if Ghostty supports having a configuration file in encodings other than UTF-8. I'm also not sure if it converts other encodings to UTF-8. ↩

[mitchellh]

I actually started working on this, but it's not as simple as proposed because both legacy and Kitty have parameters that affect encoding, so we'd have to have a way to represent those. If we can design around that, then I'd be happy to accept this, I think its a useful thing.

[00-kat]

Could you provide an example as to what some of these parameters look like? I'm not too familiar with the specifics of either protocols.

[00-kat]

Here's a tentative new syntax proposal:

keybind = ctrl+space=key:ctrl+comma,foo,no-bar,baz=4

or:

keybind = ctrl+space=legacy:ctrl+comma,foo,no-bar,baz=4
keybind = ctrl+alt+space=kitty:super+numlock+f24,foo,no-bar,baz=4

This would fit in most with the current syntax, but having a third layer of =s feels like it may be confusing.

I'm not sure what these modifiers are like or their types, so this is probably pretty incorrect.