Skip to content

terminal-setup.md

Latest commit

 

History

History
110 lines (77 loc) · 4 KB

terminal-setup.md

File metadata and controls

110 lines (77 loc) · 4 KB
Raw

Terminal Setup

Base Context uses the Kitty keyboard protocol for reliable modifier key detection. Most modern terminals support this protocol, but some require configuration.

Kitty, iTerm2

Work out of the box.

Ghostty

Add to your Ghostty config (~/Library/Application Support/com.mitchellh.ghostty/config on macOS, ~/.config/ghostty/config on Linux):

keybind = alt+backspace=text:\x1b\x7f

Older Claude Code versions may have added this Ghostty mapping:

keybind = shift+enter=text:\n

That mapping sends a raw linefeed byte. Inside Base Context, that is indistinguishable from Ctrl+J, so tmux and Base Context no longer see a real shift+enter key event.

If Claude Code 2.x or newer is the only reason you added that mapping, you can remove it, unless you want to use Claude Code in tmux, where it still requires that Ghostty mapping.

If you want Shift+Enter to keep working in tmux via that remap, add ctrl+j to your Base Context newLine keybinding in ~/.base-context/keybindings.json:

{
  "newLine": ["shift+enter", "ctrl+j"]
}

WezTerm

Create ~/.wezterm.lua:

local wezterm = require 'wezterm'
local config = wezterm.config_builder()
config.enable_kitty_keyboard = true
return config

VS Code (Integrated Terminal)

keybindings.json locations:

  • macOS: ~/Library/Application Support/Code/User/keybindings.json
  • Linux: ~/.config/Code/User/keybindings.json
  • Windows: %APPDATA%\\Code\\User\\keybindings.json

Add to keybindings.json to enable Shift+Enter for multi-line input:

{
  "key": "shift+enter",
  "command": "workbench.action.terminal.sendSequence",
  "args": { "text": "\u001b[13;2u" },
  "when": "terminalFocus"
}

Windows Terminal

Add to settings.json (Ctrl+Shift+, or Settings → Open JSON file) to forward the modified Enter keys Base Context uses:

{
  "actions": [
    {
      "command": { "action": "sendInput", "input": "\u001b[13;2u" },
      "keys": "shift+enter"
    },
    {
      "command": { "action": "sendInput", "input": "\u001b[13;3u" },
      "keys": "alt+enter"
    }
  ]
}
  • Shift+Enter inserts a new line.
  • Windows Terminal binds Alt+Enter to fullscreen by default. That prevents Base Context from receiving Alt+Enter for follow-up queueing.
  • Remapping Alt+Enter to sendInput forwards the real key chord to Base Context instead.

If you already have an actions array, add the objects to it. If the old fullscreen behavior persists, fully close and reopen Windows Terminal.

xfce4-terminal, terminator

These terminals have limited escape sequence support. Modified Enter keys like Ctrl+Enter and Shift+Enter cannot be distinguished from plain Enter, preventing custom keybindings such as submit: ["ctrl+enter"] from working.

For the best experience, use a terminal that supports the Kitty keyboard protocol:

IntelliJ IDEA (Integrated Terminal)

The built-in terminal has limited escape sequence support. Shift+Enter cannot be distinguished from Enter in IntelliJ's terminal.

If you want the hardware cursor visible, set BASE_CONTEXT_HARDWARE_CURSOR=1 before running base-context (disabled by default for compatibility).

Consider using a dedicated terminal emulator for the best experience.

macOS Control+Option+Arrow shortcuts

Pending-message reordering defaults to Control+Option+Up and Control+Option+Down. Base Context accepts modern modified-arrow sequences and legacy Option-as-Meta wrapped Control+Arrow sequences. macOS VoiceOver uses Control+Option as its modifier, and system or terminal shortcuts can intercept these chords before they reach Base Context. If that happens, remap app.message.moveEarlier and app.message.moveLater in ~/.base-context/keybindings.json.