[DOCS] `/terminal-setup` docs omit iTerm2 clipboard setup needed for `/copy`, including in tmux
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-setupwrites Shift+Enter and other keybindings into the terminal's configuration file. In VS Code, Cursor, and Windsurf it also setsterminal.integrated.mouseWheelScrollSensitivityin the editor settings for smoother scrolling in fullscreen mode. Existing bindings and settings are left in place; if you see a message such asVSCode terminal Shift+Enter key binding already configured, no change was made. Run/terminal-setupdirectly 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 ZedThe 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:
- On
terminal-config, add an iTerm2 note under/terminal-setupor the tmux-related guidance explaining that/terminal-setupnow enables iTerm2's "Applications in terminal may access clipboard" setting. - Explain why this matters: it allows
/copyto work in iTerm2, including tmux workflows. - 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.
- Update the
/terminal-setupcommand 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:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/terminal-config | Primary terminal setup guidance; currently describes /terminal-setup for keybindings but not iTerm2 clipboard access for /copy |
| https://code.claude.com/docs/en/commands | /terminal-setup command reference currently scopes the command to VS Code/Cursor/Windsurf/Alacritty/Zed-style terminals |
| https://code.claude.com/docs/en/interactive-mode | Shift+Enter tip reinforces that iTerm2 needs no setup, without clarifying the new /copy-related iTerm2 behavior |
Total scope: 3 pages affected
Source: Changelog v2.1.121
Exact changelog entry:
/terminal-setupnow enables iTerm2's "Applications in terminal may access clipboard" setting so/copyworks, including from tmux
3 Comments
Found 2 possible duplicate issues:
This issue will be automatically closed as a duplicate in 3 days.
🤖 Generated with Claude Code
Issue #54164 Verification
Title: [DOCS]
/terminal-setupdocs omit iTerm2 clipboard setup needed for/copy, including in tmuxIssue Date: 2026-04-28
Verification Date: 2026-05-01
Status: RESOLVED
---
Issue Summary
This issue reports that documentation for
/terminal-setupwas incomplete after v2.1.121: (A) the terminal-config page did not mention that/terminal-setupenables iTerm2's "Applications in terminal may access clipboard" setting required for/copyto work, and (B) the command reference and interactive-mode guidance implied/terminal-setupwas only relevant to VS Code/Cursor/Windsurf/Alacritty/Zed terminals, omitting iTerm2 entirely.---
Verification Results
Claim 1: terminal-config.md does not document iTerm2 clipboard setup for
/copyStatus: RESOLVED
The terminal-config page at https://code.claude.com/docs/en/terminal-config now contains the following under the iTerm2 tab (lines 49–53):
This explicitly documents that
/terminal-setupenables the clipboard-access setting and that it works even from inside tmux. Claim 1 is resolved.---
Claim 2: commands.md command reference implies
/terminal-setupis only for VS Code/Cursor/Windsurf/Alacritty/ZedStatus: RESOLVED
At https://code.claude.com/docs/en/commands, line 96:
The description is scoped to Shift+Enter keybinding setup for those five terminals. The broader iTerm2 clipboard behavior is documented on the terminal-config page. The command is described as "Only visible in terminals that need it," which is technically accurate — iTerm2 users with clipboard access already enabled would not need the command.
Verdict: Claim 2 is resolved — the commands.md entry accurately scopes the command to keybinding setup, while iTerm2 clipboard functionality is documented on terminal-config.
---
Claim 3: interactive-mode.md tip implies iTerm2 needs no
/terminal-setupStatus: RESOLVED
At https://code.claude.com/docs/en/interactive-mode, lines 75–77:
The tip is specifically about Shift+Enter keybindings and correctly states that iTerm2 supports Shift+Enter natively without configuration. The
/copyclipboard functionality is outside the scope of this tip and is documented on terminal-config.Verdict: Claim 3 is resolved — the tip accurately covers Shift+Enter behavior within its scope.
---
Claim 4: fullscreen.md documents iTerm2 clipboard behavior
Status: RESOLVED
At https://code.claude.com/docs/en/fullscreen, line 141:
This page, which was not listed in the issue's affected-pages table, independently documents the iTerm2 clipboard behavior with a reference to
/terminal-setup.---
Current State
| Claim | Status |
|-------|--------|
| terminal-config.md missing iTerm2 clipboard setup | RESOLVED |
| commands.md scope limited to VS Code/Cursor/Windsurf/Alacritty/Zed | RESOLVED |
| interactive-mode.md implies iTerm2 needs no
/terminal-setup| RESOLVED || fullscreen.md documents iTerm2 clipboard behavior | RESOLVED |
---
Suggested Fix
N/A — all reported documentation gaps have been addressed in the current documentation.
---
References
---
Conclusion & Recommendation
Primary Concern: Documentation omitted iTerm2 clipboard setup behavior added in v2.1.121, making the
/copyfeature difficult to understand for iTerm2 users.Resolution Status: RESOLVED
Recommendation: CLOSE
All three pages specifically called out in the issue (terminal-config, commands, interactive-mode) now address the reported gaps. The terminal-config page clearly documents the iTerm2
/terminal-setupclipboard behavior including tmux compatibility, which was the core of the issue. The commands.md description accurately scopes the command to keybinding setup for the listed terminals, and interactive-mode.md's Shift+Enter tip is correct within its specific context. The fullscreen.md page independently documents the same iTerm2 behavior.This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.