Skip to content
Signalcraft
日本語

← Back to Signalcraft

Troubleshooting TUI Keybindings in AI CLIs

Troubleshooting TUI Keybindings in AI CLIs

Sometimes Shift+Enter sends a prompt instead of inserting a newline in an AI CLI. Treating that as a TUI bug and searching only the application settings can hide the real issue: the terminal may have sent the same input as Enter.

This note separates the terminal, shell, and TUI layers, then checks Codex /keymap, an external editor, Vim mode, and the status line. Key names and defaults change with products and versions, so the help shown by the running TUI is more reliable than a fixed shortcut list.

Input passes through three layers

Keyboard
  -> Windows Terminal / iTerm / WezTerm
  -> WSL / SSH / shell
  -> Codex or OpenCode TUI

No layer is required to pass the label “Shift+Enter” unchanged. If the terminal sends the same carriage return as Enter, the TUI cannot distinguish the two keys. tmux and SSH add more places where input may be translated.

Try the same key in another terminal, without tmux or SSH. If the behavior changes, restore one boundary at a time before changing the application configuration.

Compare Shift+Enter with Ctrl+J

Enter commonly submits or accepts input, so a multiline composer needs another newline path. Shift+Enter works only when the terminal preserves a distinction. Ctrl+J often travels as a line-feed character and can be a simpler fallback, although the TUI still has to handle it.

Use this order:

  1. Display the current TUI help or Codex /keymap.
  2. Check whether Ctrl+J inserts a newline in the composer.
  3. If using Shift+Enter, check that the terminal sends it distinctly from Enter.
  4. Look for conflicts in the terminal, shell, and TUI.

The Codex developer commands reference says that /keymap can inspect and change shortcuts and persists them in tui.keymap in config.toml. Names such as ctrl-a and shift-enter are the key names recognized by the TUI, not a guarantee that every terminal can produce them.

Move long input to an external editor

Long specifications and logs do not have to be edited inside the TUI. The Codex CLI customization guide says that Ctrl+G opens the editor in VISUAL, or EDITOR when VISUAL is not set.

export VISUAL=vim
export EDITOR=vim

Writing a long request in the external editor and returning it to the composer reduces differences in newline, undo, and paste behavior. The environment variables depend on the shell and operating system, so verify the editor with a short input first.

TUI Vim mode is separate from shell vi mode

Codex /vim switches the current session’s composer to Vim mode. If the CLI supports enabling it by default, check the configuration name in the versioned reference before considering a setting such as:

[tui]
vim_mode_default = true

Setting set -o vi in the shell does not necessarily configure the TUI composer. Treat shell line editing and TUI line editing as separate layers.

OpenCode documents its available operations in Keybinds. When using both tools, align only the four operations that matter most—movement, submit, newline, and cancel—instead of forcing their entire configuration formats to match.

Keep the status line to useful signals

Codex /statusline can show and reorder the model, reasoning setting, context, rate limits, Git branch, token counters, session ID, working directory, and version. The official reference says the result is persisted in tui.status_line in config.toml.

A practical always-on selection is four or five items:

  • Model and reasoning setting
  • Remaining context
  • Git branch
  • Working directory or project name
  • Rate limits

If a narrow terminal wraps the footer, remove the session ID and detailed token counters. Inspect them only when needed. The status line is primarily a guard against using the wrong worktree or model, not a place to display every metric.

A diagnosis order for an unresponsive key

Use this sequence to identify where the input disappears:

  1. Record the Codex or OpenCode version and the TUI key configuration.
  2. Try another terminal without tmux or SSH.
  3. Check TUI /keymap and operating-system or terminal shortcut conflicts.
  4. Check how the same key arrives at the shell.
  5. If necessary, standardize on Ctrl+J or the external editor.

Key behavior is not determined by application settings alone. Adopt an input that the environment can distinguish reliably, then customize only the few operations that are worth aligning across the terminal and TUI.