Configure your terminal

Most modern terminals work with KnightCode without additional setup. Use this page when modified keys, scrolling, links, images, colors, or input-method editor (IME) positioning do not behave as expected.

KnightCode uses extended-key protocols so terminals can distinguish combinations such as Shift+Enter and Alt+Enter from plain Enter. Terminal proxies, multiplexers, and built-in IDE terminals can change or discard that information.

Troubleshooting

Use /hotkeys to inspect KnightCode's active shortcuts. See Keybindings to change them.

Text Selection and Copy

Which side owns a mouse drag depends on the TUI mode.

In fullscreen mode, knightcode enables mouse reporting and owns text selection itself. Dragging with the primary button selects, and the selection is copied to the clipboard on release. Set fullscreenCopyOnSelect to false to keep the selection highlighted and copy it with Ctrl+X instead. To reach the terminal's own selection while knightcode captures the mouse, hold the terminal's bypass modifier — usually Shift, Option in iTerm2, and Shift+Command/Shift+Ctrl in Ghostty.

In regular mode, knightcode never enables mouse reporting, so a drag is the terminal emulator's own selection and knightcode is not involved in copying it. Use the terminal's copy shortcut — Ctrl+Shift+C on most Linux and Windows terminals, Command+C on macOS — or enable the terminal's copy-on-select option. Dragging alone does not reach the clipboard in terminals where that option is off by default, which includes Windows Terminal (copyOnSelect defaults to false) and Apple Terminal, which has no such option. Switch to fullscreen if you want drag-to-copy without depending on the terminal.

Kitty

Kitty supports the required keyboard protocol without additional configuration.

iTerm2

Regular terminal mode works without additional configuration.

Fix slow fullscreen scrolling

In fullscreen mode, KnightCode owns the viewport, so iTerm2 sends mouse-wheel reports instead of scrolling native terminal history. Fast trackpad gestures can then move only about one line at a time.

To change this behavior:

1. Open iTerm2 > Settings > Advanced.
2. Search for Trackpad scrolls fast?.
3. Set it to No.

This is an iTerm2-wide setting and can also change native trackpad scrolling. The underlying behavior is tracked in iTerm2 issue 9619.

Apple Terminal

KnightCode enables enhanced key reporting when available. If Terminal.app still sends plain Return for Shift+Enter, KnightCode uses a local macOS modifier fallback and treats it as Shift+Enter.

The fallback works only when KnightCode runs on the same Mac as Terminal.app. It cannot inspect the local modifier state when KnightCode runs on another machine over SSH.

Ghostty

Add this mapping to Ghostty's configuration if Alt+Backspace does not work:

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

The configuration file is ~/Library/Application Support/com.mitchellh.ghostty/config on macOS and ~/.config/ghostty/config on Linux.

Older Claude Code configurations may contain:

keybind = shift+enter=text:\n

This sends a raw linefeed, which KnightCode cannot distinguish from Ctrl+J. Remove the mapping if an older Claude Code installation is the only reason you added it. KnightCode already binds Ctrl+J as a newline alternative, so the mapping may appear to work while still preventing KnightCode and tmux from receiving a real Shift+Enter event.

Open links in fullscreen mode

Links remain clickable in fullscreen mode, but Ghostty does not show its normal hover underline or URL preview while KnightCode captures mouse input. Hold Shift+Command on macOS or Shift+Ctrl on Linux to use Ghostty's native link handling.

WezTerm

WezTerm normally reports Shift+Enter through xterm extended keys. To enable the Kitty keyboard protocol explicitly, create ~/.wezterm.lua:

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

Forward Alt+Enter on macOS

WezTerm binds Option+Enter to fullscreen by default on macOS. To use it for KnightCode's follow-up queue, add this entry to your config.keys table:

{
  key = 'Enter',
  mods = 'ALT',
  action = wezterm.action.SendString('\x1b[13;3u'),
}

A complete minimal configuration is:

local wezterm = require 'wezterm'
local config = wezterm.config_builder()
config.keys = {
  {
    key = 'Enter',
    mods = 'ALT',
    action = wezterm.action.SendString('\x1b[13;3u'),
  },
}
return config

Position an IME candidate window in WSL

If CJK IME candidates do not follow KnightCode's text cursor in WSL, show the hardware cursor:

export KNIGHTCODE_HARDWARE_CURSOR=1
knightcode

You can instead set showHardwareCursor to true in KnightCode settings.

Alacritty

Alacritty normally reports Shift+Enter. On macOS, Option+Enter can arrive as plain Enter. Add this to ~/.config/alacritty/alacritty.toml to forward it to KnightCode:

[[keyboard.bindings]]
key = "Enter"
mods = "Alt"
chars = "\u001b[13;3u"

Restart Alacritty after changing the file.

VS Code integrated terminal

VS Code 1.109.5 and newer enable the Kitty keyboard protocol in the integrated terminal by default.

For an older version, add a Shift+Enter terminal binding to keybindings.json:

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

The user keybindings.json file is normally located at:

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

Zed integrated terminal

Add these bindings to Zed's keymap.json:

{
  "context": "Terminal",
  "bindings": {
    "shift-enter": ["terminal::SendText", "\u001b[13;2u"],
    "ctrl--": ["terminal::SendText", "\u001b[45;5u"],
    "ctrl-alt-]": ["terminal::SendText", "\u001b[93;7u"]
  }
}

Windows Terminal

Windows Terminal uses KnightCode's Windows and WSL shortcut defaults. See Keybindings for the complete list.

Forward Shift+Enter

Open Windows Terminal's settings.json with Ctrl+Shift+, or Settings > Open JSON file. Add this object to its actions array:

{
  "command": { "action": "sendInput", "input": "\u001b[13;2u" },
  "keys": "shift+enter"
}

Fully close and reopen Windows Terminal, then verify that Shift+Enter inserts a new line in KnightCode.

Use Alt+Enter for follow-ups

Windows Terminal binds Alt+Enter to fullscreen by default. KnightCode therefore uses Ctrl+Q for follow-ups on Windows and WSL.

To use Alt+Enter instead, configure Windows Terminal to forward the key and bind app.message.followUp to alt+enter in KnightCode's keybindings.json. See Keybindings.

xfce4-terminal and Terminator

These terminals cannot reliably distinguish modified Enter keys from plain Enter. Custom bindings such as Ctrl+Enter or Shift+Enter therefore may not work.

Use a terminal with modern extended-key support when you need those shortcuts, such as Kitty, Ghostty, WezTerm, iTerm2, Windows Terminal, or a compatible Alacritty build.

IntelliJ IDEA integrated terminal

IntelliJ IDEA's built-in terminal cannot reliably distinguish Shift+Enter from plain Enter. Use Ctrl+J for a newline or run KnightCode in a terminal with modern extended-key support.

If an IME candidate window does not follow the text cursor, show the hardware cursor:

export KNIGHTCODE_HARDWARE_CURSOR=1
knightcode

Override detected capabilities

KnightCode automatically detects OSC 8 hyperlinks, inline image protocols, and truecolor support. A terminal proxy or multiplexer can make that detection inaccurate.

Settings take precedence over environment variables. An unset value or auto preserves automatic detection.

Only force a capability supported by the complete terminal path. Unsupported escape sequences can corrupt rendering. See Environment Variables and Settings for the canonical value definitions.

Program status

KnightCode reports its state with the Program Status Protocol (OSC 7501), so terminals and agent dashboards can show whether it is working, waiting for you, done, or failed:

Reports never contain prompts or model output. KnightCode sends them only after the terminal answers the protocol's support query; tmux and screen do not forward them. Set KNIGHTCODE_PROGRAM_STATUS=1 to send reports without asking, or KNIGHTCODE_PROGRAM_STATUS=0 to turn them off.