claude-code - 💡(How to fix) Fix [Docs] Apple Terminal listed in "Works without setup" for Shift+Enter, but Shift+Enter submits instead of inserting a newline

Preflight Checklist

• I searched existing issues. The closest are #2946, #7958, and #9321 — all closed and all filed as behavior bugs ("Shift+Enter should insert a newline"). This report is different: it's a documentation-accuracy issue about a specific, currently-live claim in the docs, not a request to change runtime behavior.
• Single issue.
• Latest version (Claude Code 2.1.150).

What's wrong

Two doc pages state that Apple Terminal supports Shift+Enter for newline with no configuration. On a default Apple Terminal this is not true — Shift+Enter submits the prompt instead of inserting a newline.

1. terminal-config.md (https://code.claude.com/docs/en/terminal-config) — the "Enter multiline prompts" table:

| Ghostty, Kitty, iTerm2, WezTerm, Warp, Apple Terminal, Windows Terminal | Works without setup |

2. interactive-mode.md (https://code.claude.com/docs/en/interactive-mode) — the "Multiline input" table and the Tip below it:

| Shift+Enter | Shift+Enter | Native in iTerm2, WezTerm, Ghostty, Kitty, Warp, Apple Terminal, Windows Terminal |

Shift+Enter works without configuration in iTerm2, WezTerm, Ghostty, Kitty, Warp, Apple Terminal, and Windows Terminal.

Why it's wrong

In testing on a default Apple Terminal, Shift+Enter submits the prompt — identical to plain Enter — while Ctrl+J and \+Enter correctly insert a newline. The cause is that Apple Terminal emits the same byte, carriage return (0x0d), for both Enter and Shift+Enter, so there is no distinct sequence for Claude Code to bind a newline to. This is straightforward to confirm with a hex dump of terminal input.

The docs corroborate that Claude Code distinguishes the two keystrokes by the byte the terminal sends, not by the Shift modifier itself: the tmux section of terminal-config.md notes that the extended-keys settings (tmux's hook into xterm's modifyOtherKeys / extended-keys mechanism) let tmux "distinguish Shift+Enter from plain Enter so the newline shortcut works." A terminal that sends an identical byte for both therefore can't drive the shortcut. The "Enable Option key shortcuts on macOS" section of the same page also documents that Apple Terminal needs explicit setup for the Option+Enter path — so there's precedent in the docs for Apple Terminal requiring configuration for key shortcuts.

Steps to reproduce

1. Open Apple Terminal (default profile, no /terminal-setup, not inside tmux).
2. Run claude.
3. Type a word, press Shift+Enter, type another word.
4. Observe: the message submits on Shift+Enter instead of inserting a newline. (Ctrl+J and \+Enter correctly insert a newline.)

Environment

• Claude Code: 2.1.150
• OS: macOS 26.5 (build 25F71)
• Terminal: Apple Terminal 2.15
• Shell: zsh
• Not inside tmux; /terminal-setup not run.

Suggested fix (docs)

Move Apple Terminal out of the "Works without setup" / "Native" rows on both pages, and point Terminal.app users to the methods that work there — Ctrl+J or \+Enter. There is no first-party Apple Terminal setting that produces a distinct Shift+Enter: the Settings → Profiles → Keyboard pane has a key-mapping table and a "Use Option as Meta Key" toggle, but the mapping table doesn't accept a Shift+Return combination and Option-as-Meta affects Option, not Shift. (The only known route to the literal Shift+Enter key is an OS-level remapper such as Karabiner-Elements — a community workaround, not something for the docs to present as setup.)

Happy to open a docs PR for this.