[DOCS] Setup docs missing `claude-cli://` deep-link terminal selection behavior

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/setup

Section/Topic

Installation / OS integration behavior for claude-cli:// deep links

Current Documentation

The setup page currently says:

This page covers system requirements, platform-specific installation details, updates, and uninstallation.

Its uninstall section also documents local install artifacts:

To remove Claude Code, follow the instructions for your installation method. rm -f ~/.local/bin/claude rm -rf ~/.local/share/claude

No documentation currently exists on this page for claude-cli:// deep links, which terminal they open in, or how terminal selection works.

The only current mention of this behavior in the docs is the changelog:

Deep links (claude-cli://) now open in your preferred terminal instead of whichever terminal happens to be first in the detection list

What's Wrong or Missing?

Claude Code v2.1.84 changed user-visible deep-link behavior, but the main docs never explain:

• that claude-cli:// deep links exist
• that opening one launches Claude Code in a terminal
• that terminal selection now respects the user's preferred terminal instead of detection-order behavior
• what “preferred terminal” means in practice, or how users can predict which terminal a deep link will open

Users with multiple terminal apps installed cannot tell from the docs which app a claude-cli:// link will open, or why that behavior changed in v2.1.84.

Suggested Improvement

Add a short claude-cli:// deep-links subsection to the setup page (or a dedicated page linked from setup) that explains:

• what the deep links are for
• that opening a deep link launches Claude Code in the user's preferred terminal
• how terminal choice is determined at a high level
• that v2.1.84 changed this from detection-order behavior to preferred-terminal behavior

If terminal choice is not directly configurable in Claude Code, the docs should say that explicitly so users know the behavior follows system/app preference rather than a Claude-specific setting.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/setup | Primary install/integration page; best location for documenting claude-cli:// deep links and terminal-launch behavior |
| https://code.claude.com/docs/en/terminal-config | Cross-reference page for users choosing among multiple terminal apps |

Total scope: 2 pages affected

Source: Changelog v2.1.84

Exact changelog entry:

Deep links (claude-cli://) now open in your preferred terminal instead of whichever terminal happens to be first in the detection list