[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/clauderm -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
4 Comments
Still unresolved as of 2026-04-11. I rechecked https://code.claude.com/docs/en/setup and https://code.claude.com/docs/en/settings; the docs mention the
claude-cli://protocol handler and thedisableDeepLinkRegistrationsetting, but I couldn't find any current documentation that deep links open in the user's preferred terminal. Keeping this open.Just checked the current docs again. This issue is not fully resolved yet.
Issue #39104 Verification
Title: [DOCS] Setup docs missing
claude-cli://deep-link terminal selection behaviorIssue Date: 2026-03-26
Verification Date: 2026-05-28
Status: RESOLVED
---
Issue Summary
This issue reports that Claude Code v2.1.84 changed
claude-cli://deep-link terminal selection to use the user's preferred terminal instead of first-detected order, but the main documentation (especially the setup page) did not explain what deep links are, that they open Claude Code in a terminal, or how users can predict which terminal emulator will open.---
Verification Results
Claim 1: No documentation explains that
claude-cli://deep links exist or launch Claude Code in a terminalStatus: RESOLVED
At https://code.claude.com/docs/en/deep-links, line 9:
At https://code.claude.com/docs/en/deep-links, lines 28-33, the "How it works" section describes the OS handing off the URL, Claude Code starting, and a new terminal window opening with the prompt pre-filled.
Verdict: A dedicated deep-links page now documents the scheme, handler flow, and terminal launch behavior. This goes beyond changelog-only coverage.
---
Claim 2: No documentation explains preferred-terminal selection for deep links (v2.1.84 behavior)
Status: RESOLVED
At https://code.claude.com/docs/en/deep-links, line 161:
At https://code.claude.com/docs/en/deep-links, lines 183-185, troubleshooting for "The link opens the wrong terminal" gives per-OS guidance on how to steer which emulator opens.
At https://code.claude.com/docs/en/settings, line 203,
disableDeepLinkRegistrationlinks to the deep-links page and describes protocol-handler registration.Verdict: Current docs explain preferred/recent-terminal behavior on macOS,
$TERMINALon Linux, and fixed priority order on Windows. The v2.1.84 changelog entry remains at https://code.claude.com/docs/en/changelog (line 1526), but user-facing behavior is now documented outside the changelog.---
Claim 3: Users cannot tell from the docs which terminal a deep link will open
Status: RESOLVED
The deep-links page documents platform-specific terminal selection rules (line 161) and actionable troubleshooting when the wrong terminal opens (lines 183-185). Users with multiple terminal apps can determine expected behavior per OS.
Verdict: The predictability gap described in the issue is addressed on the deep-links page.
---
Claim 4: The setup page should document or link to deep-link terminal behavior
Status: RESOLVED
At https://code.claude.com/docs/en/setup, there is still no
claude-cli://subsection. However, the issue's suggested fix allowed either a setup subsection or a dedicated page linked from setup-related docs. A dedicated page at https://code.claude.com/docs/en/deep-links now covers the full topic, and https://code.claude.com/docs/en/settings (line 203) and https://code.claude.com/docs/en/vs-code (line 295) cross-reference it. The substantive documentation gap is closed even though setup itself does not yet mention deep links.Verdict: The material missing content exists in canonical user docs; setup-page placement was a location suggestion, not an unresolved functional gap.
---
Current State
| Claim | Status |
|-------|--------|
| Deep links and terminal launch undocumented | RESOLVED |
| Preferred-terminal selection undocumented | RESOLVED |
| Users cannot predict which terminal opens | RESOLVED |
| Setup page lacks deep-link section/link | RESOLVED (dedicated page + cross-links) |
---
Suggested Fix
N/A - issue has been resolved.
---
References
disableDeepLinkRegistrationwith link to deep-links documentation---
Conclusion & Recommendation
Primary Concern: Documentation did not explain
claude-cli://deep links or how terminal emulator selection works when a link opens.Resolution Status: RESOLVED
Recommendation: CLOSE
The deep-links page and related cross-references now document deep-link existence, terminal launch behavior, and per-platform terminal selection. The original gap (changelog-only mention) no longer applies.
---
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.