If you use Zellij as your terminal multiplexer on macOS, you’ve probably hit the same wall I did: the default keybindings are built around Ctrl, but on macOS inside a modern terminal like Ghostty, Ctrl is a warzone. This post documents the full journey of finding a setup that actually works — including all the wrong turns.

The Problem with Ctrl on macOS

Zellij’s defaults use Ctrl as the modifier for every mode-entry key: Ctrl+T for tabs, Ctrl+P for panes, Ctrl+O for sessions, and so on. On macOS, this causes immediate conflicts:

• Ghostty binds Ctrl+T to open a new tab
• Amp CLI and opencode CLI use several Ctrl+ combos internally
• Many other terminal tools treat Ctrl as their own domain

The obvious fix is to switch to a different modifier. But finding one that’s actually clean turns out to be harder than it sounds.

Attempt 1: Cmd as Leader

The first instinct on macOS is to reach for Cmd. It feels native, it’s easy to reach, and it’s what macOS apps use for everything important — which is exactly the problem. Cmd+Q quits apps, Cmd+T opens tabs in Ghostty, Cmd+W closes windows. There’s essentially no safe Cmd+letter space left for a terminal multiplexer. This idea was dropped immediately.

Attempt 2: Alt (Option) as Leader

Alt seemed more promising. It’s less used by macOS system shortcuts, and Ghostty doesn’t claim many Alt+ combos by default. The plan was to use left Option as Alt for Zellij, and keep right Option for typing special characters like © and þ.

Ghostty supports this cleanly with one config line:

# ~/.config/ghostty/config
macos-option-as-alt = left

Note: the setting is macos-option-as-alt, not option-as-alt — the macos- prefix is required and its absence produces an “unknown field” error on config reload.

This worked at the Ghostty level, but a new problem surfaced immediately: Alt+P was triggering random behaviour at the zsh prompt. The culprit wasn’t Ghostty — it was readline. zsh’s readline layer binds Alt+P to backwards history search, so it was intercepting the keypress before Zellij ever saw it. The same issue exists for Alt+N, Alt+F, Alt+B, and several other letters that readline claims as editing shortcuts.

Worse, Zellij itself uses Alt+P as a default binding (cycle pane focus), so the conflict was happening at two levels simultaneously.

Attempt 3: Trying to Work Around Alt Conflicts

The next idea was to keep Alt but surgically remove the conflicting readline bindings in zsh:

bindkey -r '\ep'   # remove Alt+P in zsh

This works for specific keys, but the list of Alt+letter bindings claimed by readline is long. After auditing all of Zellij’s default Alt+ bindings against readline’s defaults, it became clear that almost every useful letter was already spoken for by either readline or Zellij’s own built-in shortcuts. A clean Alt-based setup would require unbinding half of zsh’s editing shortcuts — not a great trade.

The F-Key Idea

At this point, function keys came up as an alternative. F-keys aren’t used by most CLI tools, aren’t grabbed by zsh readline, and Ghostty passes them through cleanly. The concern was macOS system-level conflicts.

A quick test confirmed that pressing Fn+F9 inside Ghostty and running cat -v prints ^[[20~ — meaning Ghostty is forwarding the keycode to the terminal application. Zellij can bind to it using the simple string "F9" in config.

The ergonomic concern was real: on a MacBook with a Touch Bar, there are no physical F-keys. Every function key press requires Fn+F9, Fn+F10, etc. — a two-key combination every time. For a key used constantly as a leader, this would be miserable. But the conclusion here was pragmatic: the modes in question (tab, pane, session) aren’t used that frequently. Pressing Fn+F9 a handful of times per session is acceptable.

The F11 Casualty

The initial F-key plan assigned:

• F9 → Tab mode
• F10 → Pane mode
• F11 → Session mode

This lasted about five minutes before F11 turned out to be macOS’s Show Desktop shortcut (Mission Control). Even inside Ghostty, Fn+F11 was triggering the desktop animation. F11 was swapped out for F12, which produced no macOS-level conflict in practice.

The clear-defaults=true Lesson

An earlier config iteration without clear-defaults=true produced bizarre behaviour — typing the letter t in the shell would silently vanish, p would do nothing, and several other letters were being eaten. The root cause: Zellij’s bind "F9" "t" syntax does not mean “F9 then t” as a sequence. It means F9 or t — both keys independently trigger the same action. So every time the letter t was typed in normal mode, Zellij was intercepting it as a mode-entry key.

Adding clear-defaults=true to the keybinds block wipes all built-in bindings, ensuring nothing bleeds through unexpectedly:

keybinds clear-defaults=true {
    ...
}

The Final Configuration

After all of that, the working setup is:

Ghostty config (~/.config/ghostty/config):

macos-option-as-alt = left

Zellij keybindings (~/.config/zellij/config.kdl):

Inside each mode, navigation uses plain h/j/k/l keys with no modifier — this is Zellij’s modal design working as intended. You enter a mode once, do what you need, and Esc returns you to normal.

The Alt+ shortcuts for focus movement and new panes are kept from Zellij’s stock defaults. Left Option now sends proper Alt keycodes thanks to the Ghostty config, so these work without any special handling.

Lessons Learned

A few things worth knowing before you start this journey yourself:

There is no perfect modifier on macOS. Every key has claimed territory somewhere — Cmd in system/app shortcuts, Ctrl in readline and CLI tools, Alt in readline’s line-editing bindings. The best you can do is find the modifier whose conflicts matter least for your specific workflow.

Test keycodes before configuring. Running cat -v and pressing your candidate key inside the terminal tells you immediately whether it’s being forwarded or swallowed. This saves a lot of config-reload cycles.

clear-defaults=true is almost always what you want when doing significant keybinding overhauls. Zellij’s default config is additive — without clearing it, you’ll have phantom bindings from the built-in defaults layered under your custom ones.

Zellij’s modal design rewards commitment. The temptation is to make everything a single-key shortcut available at all times, like tmux’s prefix model. But Zellij’s modes are genuinely more efficient once you lean into them — three F-key presses to enter a mode, then free navigation with plain letters, beats modifier-chording every single action.