@knightcodeai/cli 0.17.3 → 0.18.0

package/docs/terminal-setup.md

@@ -0,0 +1,242 @@
+# 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
+
+| Symptom | Start here |
+|---|---|
+| `Shift+Enter` submits instead of inserting a line | Your terminal's section below; for tmux, see [Run KnightCode in tmux](tmux.md) |
+| `Alt+Enter` does not queue a follow-up | [WezTerm](#wezterm), [Alacritty](#alacritty), or [Windows Terminal](#windows-terminal) |
+| Fullscreen scrolling is unusually slow | [iTerm2](#iterm2) |
+| Dragging does not copy text, or copies it unexpectedly | [Text Selection and Copy](#text-selection-and-copy) |
+| Links work but show no hover preview | [Ghostty](#ghostty) |
+| Inline images or colors are not detected | [Override detected capabilities](#override-detected-capabilities) |
+| An IME candidate window appears in the wrong place | [WezTerm](#wezterm) or [IntelliJ IDEA](#intellij-idea-integrated-terminal) |
+| Modified keys fail only inside tmux | [Run KnightCode in tmux](tmux.md) |
+
+Use `/hotkeys` to inspect KnightCode's active shortcuts. See [Keybindings](keybindings.md) to change them.
+
+## Text Selection and Copy
+
+Which side owns a mouse drag depends on the [TUI mode](usage.md#adjust-the-terminal).
+
+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](https://gitlab.com/gnachman/iterm2/-/work_items/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:
+
+```text
+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:
+
+```text
+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`:
+
+```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:
+
+```lua
+{
+  key = 'Enter',
+  mods = 'ALT',
+  action = wezterm.action.SendString('\x1b[13;3u'),
+}
+```
+
+A complete minimal configuration is:
+
+```lua
+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:
+
+```bash
+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:
+
+```toml
+[[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`:
+
+```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`:
+
+```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](keybindings.md) 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:
+
+```json
+{
+  "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](keybindings.md#assign-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:
+
+```bash
+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.
+
+| Capability | Environment variable | Setting |
+|---|---|---|
+| Hyperlinks | `KNIGHTCODE_HYPERLINKS=1\|0\|auto` | `terminal.hyperlinks: true\|false\|"auto"` |
+| Inline images | `KNIGHTCODE_IMAGE_PROTOCOL=kitty\|iterm2\|none\|auto` | `terminal.images: "kitty"\|"iterm2"\|false\|"auto"` |
+| Truecolor | `KNIGHTCODE_TRUE_COLOR=1\|0\|auto` | `terminal.trueColor: true\|false\|"auto"` |
+
+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](environment-variables.md#knightcode-process-configuration) and [Settings](settings.md) for the canonical value definitions.
+
+## Program status
+
+KnightCode reports its state with the [Program Status Protocol (OSC 7501)](https://www.superlogical.com/rex/docs/build/program-status), so terminals and agent dashboards can show whether it is working, waiting for you, done, or failed:
+
+| State | When |
+|---|---|
+| `working` | An agent run or compaction is in progress. The message is the session name. |
+| `blocked` | An extension dialog or login waits for you. The message is the dialog title. |
+| `done` | A run finished. The message is the session name. |
+| `error` | A run ended with an error that is not retried. The message is the first line of the error. |
+| `idle` | KnightCode started, or you cancelled the run. |
+
+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.

package/docs/termux.md

@@ -0,0 +1,117 @@
+# Run KnightCode on Android with Termux
+
+KnightCode runs on Android through [Termux](https://termux.dev/), a terminal emulator and Linux environment. Text input, file tools, and shell commands are supported. KnightCode can copy and paste text through the Android clipboard with Termux:API. Clipboard image paste is not supported.
+
+## Before you begin
+
+Install Termux from [GitHub or F-Droid](https://github.com/termux/termux-app#installation). Do not use the deprecated Google Play build.
+
+[Termux:API](https://github.com/termux/termux-api#installation) is optional. Install it only when you want KnightCode to copy or paste Android clipboard text, or when shell commands need Android device APIs.
+
+## Install KnightCode
+
+1. Update Termux packages:
+
+   ```bash
+   pkg update && pkg upgrade
+   ```
+
+2. Install Node.js and Git:
+
+   ```bash
+   pkg install nodejs git
+   ```
+
+3. Install KnightCode:
+
+   ```bash
+   npm install -g --ignore-scripts @knightcodeai/cli
+   ```
+
+4. Verify the installation:
+
+   ```bash
+   knightcode --version
+   ```
+
+5. Open the folder you want to work in and start KnightCode:
+
+   ```bash
+   cd /path/to/working-folder
+   knightcode
+   ```
+
+Continue with the main [Quickstart](quickstart.md#3-choose-a-model) to connect a model and run your first task.
+
+## Access Android shared storage
+
+Termux cannot access shared Android storage until you grant permission. Run this once:
+
+```bash
+termux-setup-storage
+```
+
+After approval, Android shared storage is available under `/storage/emulated/0` and through the links Termux creates under `~/storage/`.
+
+Only grant this permission when KnightCode should be able to access those files. Commands and tools running in Termux use the same storage permissions as the Termux process.
+
+## Use clipboard commands
+
+KnightCode uses `termux-clipboard-set` to copy text and `termux-clipboard-get` for its clipboard-paste shortcut. Shell commands can use both commands directly. Install the Termux:API app and its command-line package:
+
+```bash
+pkg install termux-api
+```
+
+Verify the integration:
+
+```bash
+printf 'KnightCode clipboard test' | termux-clipboard-set
+termux-clipboard-get
+```
+
+The second command should print `KnightCode clipboard test`.
+
+The Termux clipboard API supports text only. KnightCode's clipboard-paste shortcut inserts that text into the editor but cannot attach clipboard images.
+
+## Add Termux-specific instructions
+
+KnightCode detects that it is running in Termux, but it cannot infer how you want it to interact with Android. Add only the environment details relevant to your work to `~/.knightcode/agent/AGENTS.md`:
+
+````markdown
+# Termux environment
+
+- KnightCode runs in Termux on Android.
+- Shared Android storage is under `/storage/emulated/0`.
+- Open URLs with `termux-open-url "https://example.com"`.
+- Open files with `termux-open <path>`.
+- Do not access shared storage unless the task requires it.
+````
+
+Run `/reload` after changing the file during an active session.
+
+## Troubleshooting
+
+### Clipboard integration fails
+
+Confirm that you installed both components:
+
+1. The Termux:API Android app from the same source as Termux
+2. The `termux-api` command-line package
+
+Then run the clipboard verification commands above outside KnightCode. If they fail there, fix the Termux:API installation before retrying KnightCode's copy command.
+
+### Shared storage reports permission denied
+
+Run `termux-setup-storage`, approve the Android permission request, and retry the path under `~/storage/` or `/storage/emulated/0`.
+
+### KnightCode is not found after installation
+
+Open a new Termux shell and run:
+
+```bash
+npm prefix -g
+command -v knightcode
+```
+
+Confirm that the global npm binary directory is on `PATH`, then reinstall KnightCode if the package is missing.

package/docs/themes.md

@@ -0,0 +1,140 @@
+# Customize KnightCode with themes
+
+Themes control the colors KnightCode uses in interactive mode and HTML exports. KnightCode includes the `system` theme and the `dark` and `light` themes, warm grays with an orange accent. You can select one theme, follow your terminal's light or dark appearance, or create your own palette.
+
+## Use your terminal's colors
+
+The `system` theme is the default. It builds KnightCode's colors from your terminal's theme, so KnightCode matches the terminal instead of bringing its own palette:
+
+- KnightCode queries the terminal's default foreground and background colors and its 16 ANSI colors.
+- Each KnightCode color takes its hue from one ANSI color, for example errors from red and links from blue.
+- KnightCode sets each color's lightness so that it stands out from the background by a minimum contrast. Body text keeps at least a 4.5:1 WCAG contrast ratio on the background and every panel.
+- When the terminal switches between light and dark, KnightCode queries the colors again and rebuilds the theme.
+
+The theme adapts to what the terminal reports:
+
+| Terminal reports | Result |
+|---|---|
+| Background and ANSI colors | Colors from the terminal palette, placed for the actual background. |
+| Background only | KnightCode's own hues, placed for the actual background. |
+| Nothing | ANSI color indices and the terminal's default colors, which the terminal renders itself. Secondary text is faint, and panels have no background color. |
+
+KnightCode asks the terminal for its colors when it starts. Terminals usually answer within a few milliseconds, and KnightCode waits at most 100 ms before showing the startup header. If the terminal does not answer in time, KnightCode uses the ANSI color fallback, and it still applies the colors if they arrive later, for example over a slow SSH connection. `system` is a reserved name: a custom theme with that name is ignored.
+
+<a id="selecting-a-theme"></a>
+
+## Choose a theme
+
+Open `/settings` and select **Theme**. You can use one theme for every terminal appearance or choose separate themes for light and dark terminals.
+
+The selection is saved as the `theme` [setting](settings.md#terminal-and-display):
+
+```json
+{
+  "theme": "dark"
+}
+```
+
+Without a `theme` setting, KnightCode uses `system`.
+
+Automatic mode stores the light theme first and the dark theme second:
+
+```json
+{
+  "theme": "light/dark"
+}
+```
+
+KnightCode decides whether the terminal is light or dark from its reported background and foreground colors. If the terminal does not report its background, KnightCode uses the terminal's light/dark notification, then the `COLORFGBG` environment variable, then dark. The same decision picks the theme of a light/dark pair and the appearance of `system`. When automatic mode is active, KnightCode changes themes when the terminal reports an appearance change. Theme names cannot contain `/` because KnightCode reserves it for this setting format.
+
+Use `--use-theme` to choose the initial theme for one invocation without changing the saved setting:
+
+```bash
+knightcode --use-theme light
+knightcode --use-theme light/dark
+```
+
+See [CLI resources](cli.md#resources) for the command-line option.
+
+## Create a custom theme
+
+Copy one of the [built-in themes](https://github.com/KnightCodeAI/knightcode/tree/main/packages/cli/src/modes/interactive/theme) or create a new JSON file conforming to the [schema](https://knightcode.dev/schemas/theme.schema.json). The built-in themes use OKHSL colors, with variables for colors that several roles share, so you can adjust a hue, saturation, or lightness directly.
+
+1. Save the file as `<agent-dir>/themes/my-theme.json`. The agent directory defaults to `~/.knightcode/agent`.
+2. Set its `name` to `my-theme`.
+3. Change values in `vars` and `colors`.
+4. Select `my-theme` through `/settings`.
+
+Use the theme name as the filename. KnightCode hot-reloads the active user theme only from `<agent-dir>/themes/<name>.json`. Run `/reload` after adding or changing a theme from any other source.
+
+## Understand the theme file
+
+| Property | Required | Responsibility |
+|---|---|---|
+| `$schema` | No | Enables editor validation and completion against KnightCode's published schema. |
+| `name` | Yes | Identifies the theme in selectors and settings. It must be unique, cannot contain `/`, and cannot be `system`. |
+| `appearance` | No | `"dark"` or `"light"`: the background the theme is designed for. KnightCode detects it from the theme colors when omitted. |
+| `vars` | No | Defines reusable color values. Variables can reference other variables. |
+| `colors` | Yes | Assigns colors to terminal UI roles. The schema identifies required and optional roles. |
+| `export` | No | Overrides page and panel backgrounds in HTML exports. |
+
+Theme objects are strict: only documented top-level fields and color tokens are accepted. Define reusable custom colors under `vars`; custom keys under `colors` or `export` and additional top-level metadata are rejected.
+
+A color can be written in six forms:
+
+| Form | Example | Meaning |
+|---|---|---|
+| RGB hexadecimal | `"#0af"` or `"#00aaff"` | A three- or six-digit sRGB color. |
+| OKLCH | `"oklch(62% 0.1 200)"` | Perceptual lightness, chroma, and hue. |
+| OKHSL | `"okhsl(250 60% 55%)"` | Hue, saturation, and lightness. Saturation is relative to the most the sRGB gamut allows at that hue and lightness, so every value is in gamut and equal saturation looks equally colorful. |
+| 256-color index | `39` | An ANSI palette index from `0` through `255`. |
+| Variable reference | `"primary"` | The value of an entry in `vars`. |
+| Terminal default | `""` | The terminal's default foreground or background color. |
+
+Terminal default colors render as the terminal's own colors. Where KnightCode needs a concrete value, such as HTML export or extension color math, it uses the default colors the terminal reports, or a black or white guess based on the theme's appearance.
+
+KnightCode resolves chained variable references. A missing variable or circular reference makes the theme invalid. KnightCode uses truecolor when available, gamut-maps OKLCH to sRGB, and approximates colors for 256-color terminals. HTML exports convert OKHSL values to hexadecimal because CSS does not support them. If colors differ from their source values, check your terminal's truecolor detection and contrast settings. See [Configure Your Terminal](terminal-setup.md#override-detected-capabilities).
+
+Use the [theme JSON schema](https://knightcode.dev/schemas/theme.schema.json) for the exact properties, required colors, and accepted value types.
+
+KnightCode reports invalid theme files during startup and `/reload`.
+
+## Find the color to change
+
+Theme colors describe interface roles rather than individual components. Use these groups to find the relevant part of the schema:
+
+| Area | Color names |
+|---|---|
+| General interface | `accent`, `border*`, `text`, `muted`, `dim`, `success`, `error`, `warning` |
+| Selection and fullscreen | `selectedBg`, `searchMatch*`, `scrollbar*` |
+| Messages | `userMessage*`, `customMessage*`, `thinkingText` |
+| Tool execution | `toolPendingBg`, `toolSuccessBg`, `toolErrorBg`, `toolTitle`, `toolOutput` |
+| Markdown | `md*` |
+| Tool diffs | `toolDiff*`; added and removed rows are tinted with `toolSuccessBg` and `toolErrorBg` |
+| Syntax highlighting | `syntax*` |
+| Editor modes | `border`, mixed 35% toward `text` for contrast, frames the prompt at every thinking level; `bashMode` frames shell input |
+| HTML export | `export.pageBg`, `export.cardBg`, `export.infoBg` |
+
+The schema is the format reference. The built-in themes provide complete values that you can copy and adjust.
+
+The `thinking*` border colors are no longer used and can be removed from custom themes. Extensions that
+styled the prompt border with `getThinkingBorderColor(level)` should use `getEditorBorderColor()`.
+
+Four colors are optional and inherit another color when omitted:
+
+| Optional color | Fallback |
+|---|---|
+| `scrollbarTrack` | `muted` |
+| `scrollbarThumb` | `text` |
+| `searchMatchBg` | `selectedBg` |
+| `searchMatchText` | `text` |
+
+If `export` colors are omitted, KnightCode derives HTML page and panel backgrounds from `userMessageBg`.
+
+## Load a theme from a project or package
+
+Place a project theme in `.knightcode/themes/`. Project themes load only after [project trust](security.md#understand-project-trust) is granted.
+
+You can also load theme files and directories through the `themes` setting or distribute them in a KnightCode package. See [Configuration](configuration.md), [Settings](settings.md#resources), and [KnightCode Packages](packages.md).
+
+Each loaded theme must have a unique name. KnightCode reports duplicate names as resource collisions.

package/docs/tmux.md

@@ -0,0 +1,55 @@
+# Run KnightCode in tmux
+
+KnightCode works inside tmux, but tmux can report `Shift+Enter`, `Ctrl+Enter`, and plain `Enter` as the same key. Enable extended keys so KnightCode can distinguish them.
+
+## Check your tmux version
+
+```bash
+tmux -V
+```
+
+For tmux 3.5 or newer, use the recommended CSI-u configuration below. For tmux 3.2 through 3.4, use the older-version configuration.
+
+## Enable extended keys in tmux 3.5 or newer
+
+Add these lines to `~/.tmux.conf`:
+
+```tmux
+set -g extended-keys on
+set -g extended-keys-format csi-u
+```
+
+KnightCode requests extended-key reporting when the terminal does not provide the Kitty keyboard protocol directly. CSI-u is the most reliable format for forwarding modified keys through tmux.
+
+## Restart tmux
+
+The configuration applies to the tmux server. To guarantee that it is active, close your tmux sessions and start a new server.
+
+If you choose to stop the server from the command line, save your work first. This command terminates every session managed by that server:
+
+```bash
+tmux kill-server
+tmux
+```
+
+## Verify modified keys
+
+Start KnightCode inside the new tmux session and check that:
+
+1. `Shift+Enter` inserts a new line in the editor.
+2. `Enter` submits the prompt.
+3. `Alt+Enter` queues a follow-up on macOS and Linux. Windows and WSL use `Ctrl+Q` by default.
+
+If these keys still behave like plain `Enter`, verify that the terminal outside tmux can report modified keys. See [Configure your terminal](terminal-setup.md).
+
+## Use tmux 3.2 through 3.4
+
+These versions support extended keys but not `extended-keys-format csi-u`. Add only:
+
+```tmux
+set -g extended-keys on
+```
+
+KnightCode supports the xterm `modifyOtherKeys` format used by these versions. Restart tmux and repeat the verification steps.
+
+For older versions, upgrade tmux or use KnightCode outside tmux rather than relying on modified Enter shortcuts.