[DOCS] Clarify UX differences between Terminal CLI and VS Code Extension

[bgondell]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

No response

Section/Topic

interactive features

Current Documentation

No response

What's Wrong or Missing?

Summary
Users should be informed that the Claude Code experience differs between running in a native terminal vs. the VS Code integrated terminal/extension. Currently, this isn't documented, leading to confusion about whether observed differences are bugs or expected behavior.
The Issue
When running Claude Code in a native terminal (e.g., Windows Terminal, iTerm, etc.), certain interactive features work that don't appear in the VS Code integrated terminal:

Interactive checklists for confirming multi-step plans
Selection prompts for options
Other TTY-dependent interactive UI elements

This happens because VS Code's integrated terminal runs in a pseudo-TTY environment where some interactive prompt libraries don't render or behave the same way.
Impact
Users who primarily use Claude Code through VS Code may:

Never see certain interactive features
Miss opportunities for granular control over execution plans
Assume the simplified flow is the only experience available

Environment

OS: Windows 11
Terminals tested: Windows Terminal (full interactivity) vs VS Code integrated terminal (reduced interactivity)

Suggested Improvement

Add a section to the documentation (README or dedicated docs) that:

Lists known differences between terminal environments
Explains why these differences exist (TTY interactivity)
Helps users choose the right environment based on their needs

Impact

Low - Minor confusion or inconvenience

Additional Context

No response

[github-actions]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

[coygeek]

Issue #13528: UX Differences Between Terminal CLI and VS Code Extension

GitHub Issue: #13528
Status: VALID - Documentation gap confirmed

Issue Summary

The user reports that interactive UI features (checklists, selection prompts) do not work when running Claude Code CLI in VS Code's integrated terminal, but work correctly in native terminals like Windows Terminal. The issue requests either documentation of this limitation or a fix.

Documentation Verification

What the User Claims

• Interactive features (checkbox lists, selection prompts) don't render properly in VS Code's integrated terminal
• The same features work correctly in native Windows Terminal
• This appears to be a TTY/pseudo-TTY limitation

What the Documentation Says

VS Code Integration (vs-code.md):

• Contains a comparison table between "VS Code Extension" and "Terminal CLI"
• Table covers: Installation, Interface, Context, Best for
• Does NOT document behavior differences when running CLI inside VS Code's integrated terminal
• The comparison is Extension vs CLI, not "CLI in native terminal" vs "CLI in VS Code terminal"

Troubleshooting (troubleshooting.md):

• No mention of interactive feature limitations
• No mention of terminal-specific rendering issues
• No mention of VS Code integrated terminal limitations

Terminal Configuration (terminal-config.md):

• Documents Shift+Enter support for various terminals
• Lists supported terminals but doesn't discuss interactive UI rendering
• No mention of pseudo-TTY limitations

Interactive Mode (interactive-mode.md):

• Documents slash commands and general CLI usage
• No mention of terminal-specific behavior differences

Search Results

• No documentation mentions "TTY", "pseudo-TTY", or "pty" limitations
• No documentation discusses VS Code integrated terminal CLI behavior
• No documentation explains why interactive prompts might not render correctly

Gap Analysis

Expected	Documented
Explanation of interactive UI requirements	Not found
VS Code integrated terminal limitations	Not found
Native terminal vs integrated terminal differences	Not found
Troubleshooting for rendering issues	Not found

Verdict

VALID - This is a legitimate documentation gap.

The issue raises a real usability concern: users running Claude Code CLI in VS Code's integrated terminal may experience degraded interactive features compared to native terminal emulators. This behavior is completely undocumented.

Recommended Documentation Updates

1. VS Code Integration Page (vs-code.md):
   Add a section or note explaining:

   • CLI behavior differences when run inside VS Code's integrated terminal vs native terminals
   • Which interactive features may not render correctly
   • Recommendation to use Extension or native terminal for full interactive experience

2. Troubleshooting Page (troubleshooting.md):
   Add a section covering:

   • Interactive prompts not rendering correctly
   • Terminal compatibility requirements for interactive UI
   • Workarounds (use native terminal, use VS Code extension)

3. Terminal Configuration Page (terminal-config.md):
   Expand to include:

   • General terminal requirements for interactive features
   • Known limitations in certain terminal environments

Suggested Documentation Text

For vs-code.md:

## CLI in VS Code's Integrated Terminal

When running Claude Code CLI in VS Code's integrated terminal rather than the VS Code Extension,
some interactive features may not render correctly:

- Checkbox selection prompts
- Multi-select menus
- Progress spinners

This is due to pseudo-TTY limitations in VS Code's integrated terminal. For the best CLI
experience, use a native terminal emulator. For the best VS Code experience, use the
VS Code Extension which provides a native interface.

References

• Issue: [DOCS] Clarify UX differences between Terminal CLI and VS Code Extension #13528
• VS Code docs: code.claude.com/docs/en/vs-code.md
• Troubleshooting: code.claude.com/docs/en/troubleshooting.md
• Terminal config: code.claude.com/docs/en/terminal-config.md

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

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.