termnial_settings

Enabling Alt / Meta Keys in Terminal Emulators

zago's M+... shortcuts require the terminal emulator to send Alt (called Option on macOS) as a Meta input. The most compatible representation is an ESC prefix: Alt+V sends ESC followed by v (\x1bv). Avoid the old high-bit Meta mode unless a specific application requires it.

macOS

Ghostty

Add this to the Ghostty configuration file:

macos-option-as-alt = true

The usual macOS path is:

~/Library/Application Support/com.mitchellh.ghostty/config.ghostty

~/.config/ghostty/config.ghostty is also supported. Reload the configuration or restart Ghostty after changing it.

Reference: Ghostty configuration and macos-option-as-alt.

cmux

For cmux's TUI configuration, enable both macOS Option-as-Alt handling and Alt shortcuts:

keys.macos_option_as_alt = true
keys.alt_shortcuts = true

The same options can be represented in a JSON configuration as:

{
  "keys": {
    "macos_option_as_alt": true,
    "alt_shortcuts": true
  }
}

If Option is composing macOS special characters instead of reaching zago, check macos_option_as_alt first.

Reference: cmux TUI configuration.

iTerm2

1. Open Settings / Preferences → Profiles → Keys.
2. Set Left Option key to Esc+.
3. Set Right Option key to Esc+ as well if both Option keys should act as Meta.

Esc+ sends ESC before the character. Do not select the legacy high-bit Meta mode for normal zago use.

Reference: iTerm2 Profiles → Keys.

Windows

Windows Terminal

Windows Terminal normally sends Alt as a terminal modifier, so it usually needs no special Alt/Meta setting. If a shortcut does not reach zago:

1. Open Settings → Actions.
2. Search for the shortcut, such as Alt+Left, Alt+Right, or Alt+Up.
3. Remove or change any Windows Terminal action that intercepts it.
4. Open a new terminal tab and test again.

The important requirement is that Windows Terminal forwards the Alt sequence to the terminal application instead of using it for a tab or window command.

Linux

Graphical terminal emulators

GNOME Terminal, Konsole, xterm, and most X11/Wayland terminal emulators already send Alt/Meta as an ESC prefix. If the terminal offers an option named Meta sends Escape, Alt sends Escape, or similar, enable it.

For xterm, the equivalent setting is metaSendsEscape:

xterm -xrm 'XTerm*metaSendsEscape: true'

In Konsole, check Settings → Edit Current Profile → Keyboard and make sure custom key bindings do not intercept zago's Alt shortcuts.

References: xterm Meta Sends Escape and Konsole key bindings.

Linux virtual console

The Linux virtual console, such as Ctrl+Alt+F1, is the main Linux environment where Meta may use the old high-bit form by default. Check the current mode:

setmetamode

Switch the current virtual terminal to an ESC prefix:

setmetamode escprefix

The setting is per virtual terminal. Apply it to the terminals you use from a startup script if needed:

for tty in /dev/tty[1-6]; do
  setmetamode escprefix < "$tty"
done

Reference: setmetamode(1).

tmux, screen, and SSH

tmux, screen, and SSH generally forward the bytes received from the outer terminal; they do not normally repair Alt/Meta encoding. First verify the outermost terminal, then check tmux or screen bindings for intercepted Alt shortcuts.

Zellij

Zellij defaults to using Ctrl + <key> for mode switching (e.g. Ctrl+S for Scroll mode, Ctrl+O for Session mode, Ctrl+P for Pane mode, Ctrl+N for Resize mode, Ctrl+Q to quit Zellij) and Alt + <key> for quick pane navigation (e.g. Alt+N/Alt+P for next/previous pane, Alt+F for floating panes). These conflict significantly with zago's standard Nano-compatible keybindings (such as Ctrl+S to save, Ctrl+O to write out, Ctrl+P/Ctrl+N for cursor movement, and Alt+N/Alt+P for search and AI proposal navigation).

To use zago smoothly inside Zellij, consider the following options:

1. Use Locked Mode (Recommended):

   • Manual Toggle: Press Ctrl+G inside Zellij to enter Locked Mode. In locked mode, all Ctrl and Alt shortcuts except Ctrl+G (which unlocks) pass directly through to zago.
   • Default to Locked Mode: In your Zellij config file (~/.config/zellij/config.kdl), set:

     default_mode "locked"

   • Note: Inside zago, press Esc instead of Ctrl+G when canceling selections or prompt dialogs so you do not accidentally exit locked mode.

2. Use the tmux Keybinding Preset:

   • Zellij provides a tmux keybinding mode where multiplexer actions require a prefix key (such as Ctrl+B), freeing normal Ctrl and Alt keys for your editor.
   • You can also unbind conflicting keys in ~/.config/zellij/config.kdl.

3. Use Function Keys in zago:

   • zago supports standard F1–F12 function keys (such as F2 for Save & Exit, F3 for WriteOut, F6 for WhereIs search, F7 for Table Mode, F8 for Canvas Mode, F9/F10 for Cut/Uncut), which bypass terminal multiplexer Ctrl/Alt interceptions.

Testing Alt / Meta

Run:

cat -v

Press Alt+V. You should see something like:

^[v

^[ represents ESC. Press Ctrl+C to exit cat. You can then test zago's M+V or M+W shortcuts directly.