claude-code - 💡(How to fix) Fix [DOCS] `/terminal-setup` docs omit iTerm2 clipboard setup needed for `/copy`, including in tmux [1 comments, 2 participants]

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/terminal-config

Section/Topic

/terminal-setup guidance for iTerm2, especially the terminal configuration and tmux-related setup needed for clipboard-backed /copy

Current Documentation

The docs currently say:

For VS Code, Cursor, Windsurf, Alacritty, and Zed, /terminal-setup writes Shift+Enter and other keybindings into the terminal's configuration file. In VS Code, Cursor, and Windsurf it also sets terminal.integrated.mouseWheelScrollSensitivity in the editor settings for smoother scrolling in fullscreen mode. Existing bindings and settings are left in place; if you see a message such as VSCode terminal Shift+Enter key binding already configured, no change was made. Run /terminal-setup directly in the host terminal rather than inside tmux or screen, since it needs to write to the host terminal's configuration.

And the command reference says:

/terminal-setup | Configure terminal keybindings for Shift+Enter and other shortcuts. Only visible in terminals that need it, like VS Code, Cursor, Windsurf, Alacritty, or Zed

The interactive-mode page also says:

Shift+Enter works without configuration in iTerm2, WezTerm, Ghostty, Kitty, Warp, and Apple Terminal. For VS Code, Cursor, Windsurf, Alacritty, and Zed, run /terminal-setup to install the binding.

None of these pages mention that in v2.1.121 /terminal-setup also enables iTerm2's "Applications in terminal may access clipboard" setting so /copy works, including from tmux.

What's Wrong or Missing?

Changelog v2.1.121 added a new user-visible /terminal-setup behavior for iTerm2, but the docs still describe /terminal-setup as a command for VS Code/Cursor/Windsurf/Alacritty/Zed keybinding setup only.

A. Missing iTerm2 clipboard setup documentation

The terminal configuration docs do not tell iTerm2 users that /terminal-setup now enables the iTerm2 clipboard-access setting required for /copy to work.

B. Existing wording now implies the wrong scope

The command reference and interactive-mode guidance still imply that iTerm2 users do not need /terminal-setup, which is outdated once /terminal-setup also configures clipboard access for /copy, including when running inside tmux.

Suggested Improvement

Update the terminal docs to reflect the v2.1.121 behavior change:

1. On terminal-config, add an iTerm2 note under /terminal-setup or the tmux-related guidance explaining that /terminal-setup now enables iTerm2's "Applications in terminal may access clipboard" setting.
2. Explain why this matters: it allows /copy to work in iTerm2, including tmux workflows.
3. Clarify where users should run it: in the host iTerm2 session, not inside a nested terminal layer that cannot change the host terminal's settings.
4. Update the /terminal-setup command description (and any related interactive-mode tip) so it no longer implies the command is only relevant to VS Code/Cursor/Windsurf/Alacritty/Zed.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Source: Changelog v2.1.121

Exact changelog entry:

/terminal-setup now enables iTerm2's "Applications in terminal may access clipboard" setting so /copy works, including from tmux