[UX] Confusing "IDE disconnected" indicator during normal startup connection handshake (v2.0.72)

Summary

During the normal 7.5-second IDE connection handshake at startup, Claude Code displays "IDE disconnected" — which sounds like an error but is actually just the transient connection state.

This is confusing UX, not a functional bug. The connection works perfectly; the messaging is just misleading.

┌─────────────────────────────────────────────────────────────────┐
│  Current Behavior (Confusing)                                   │
│                                                                 │
│  0s:      Session starts                                        │
│  0-7.5s:  ❌ "IDE disconnected" ← sounds like an error!         │
│  7.5s+:   (indicator disappears)                                │
│  Result:  ✅ Cmd+Click works, connection succeeded              │
└─────────────────────────────────────────────────────────────────┘

---

Proposed Improvement

┌─────────────────────────────────────────────────────────────────┐
│  Better Behavior (Clear)                                        │
│                                                                 │
│  0s:      Session starts                                        │
│  0-7.5s:  🔄 "Connecting to IDE..."                             │
│  7.5s:    ✅ "IDE connected" (show briefly)                     │
│  8s+:     (indicator hides - everything OK)                     │
└─────────────────────────────────────────────────────────────────┘

Key improvements:

1. ✅ "Connecting to IDE..." — indicates progress, not failure
2. ✅ Brief "Connected" confirmation before hiding
3. ✅ User understands it's a normal process, not an error

---

Why This Matters

Users waste time troubleshooting a non-problem:

1. See "IDE disconnected" → think something is broken
2. Try /ide command → doesn't help (already connecting)
3. Check settings, restart, search for fixes
4. Eventually realize it works fine

Evidence: I spent hours troubleshooting this, testing across two machines, disabling configurations, before realizing the indicator just shows the connection handshake state.

---

Ground Truth Testing

To verify the connection actually works:

| Test | Result |
|------|--------|
| Wait 7.5 seconds for indicator to disappear | ✅ Disappears |
| Cmd+Click on file path after disappearance | ✅ Opens in VS Code |
| File diffs | ✅ Display in VS Code |
| All IDE features | ✅ Working perfectly |

Conclusion: Connection succeeds. Only the messaging is confusing.

---

Cross-Platform Reproduction

Tested on two machines — same confusing behavior on both:

| Environment | Platform | Result |
|-------------|----------|--------|
| Linux server via Remote SSH | Ubuntu 24.04 | 7.5s "disconnected" → disappears → works |
| MacBook local | macOS | 7.5s "disconnected" → disappears → works |

Both: CLI 2.0.72, Extension 2.0.72

---

Steps to Reproduce

1. Open VS Code integrated terminal
2. Run claude
3. Observe: Red "IDE disconnected" indicator appears
4. Wait: ~7.5 seconds
5. Observe: Indicator disappears
6. Test: Cmd+Click any file path
7. Result: File opens in VS Code (connection worked)

Expected: During steps 3-5, should show "Connecting to IDE..." instead of "IDE disconnected"

---

Current vs Proposed Messaging

| Stage | Current (Confusing) | Proposed (Clear) |
|-------|---------------------|------------------|
| 0-7.5s | ❌ "IDE disconnected" | 🔄 "Connecting to IDE..." |
| 7.5s | (silent disappearance) | ✅ "IDE connected" (1s) |
| 8s+ | (hidden) | (hidden) |

---

Related Issues

This is distinct from actual connection failures:

| Issue | Description | Difference |
|-------|-------------|------------|
| #4871 | Main IDE connectivity tracker | Actual disconnections during use |
| #4837 | VS Code disconnections | Connection drops during session |
| #6741 | Persistent "disconnected" | Indicator never clears |

This issue: Indicator shows normal handshake as if it's an error.

---

Similar "Confusing Indicator" Pattern

| Issue | Indicator Shows | Reality | Status |
|-------|-----------------|---------|--------|
| #7404 | MCP "Failed to connect" | MCP works | Closed → #1604 |
| #3998 | Network "offline" | Network works | Closed → #4420 |
| This issue | IDE "disconnected" | IDE connecting (transient) | Open |

Pattern: Status indicators showing transient states as if they're errors.

---

Impact

| Severity | Category | Description |
|----------|----------|-------------|
| None | Functionality | Everything works perfectly |
| Medium | UX | Causes user confusion and wasted troubleshooting time |
| Low | Trust | Users lose confidence in IDE integration |

---

Suggested Implementation

// Pseudocode
let connectionState = 'connecting';
let connectionStartTime = Date.now();

// During connection (0-7.5s)
if (connectionState === 'connecting') {
  statusIndicator.show('🔄 Connecting to IDE...');
}

// On successful connection
connectionManager.on('connected', () => {
  connectionState = 'connected';
  statusIndicator.show('✅ IDE connected');

  // Hide after 1 second
  setTimeout(() => {
    statusIndicator.hide();
  }, 1000);
});

// On connection failure (only if actually fails)
connectionManager.on('error', () => {
  connectionState = 'error';
  statusIndicator.show('❌ IDE connection failed');
  // Stay visible to alert user
});

---

Environment

Tested on two machines:

Machine 1: Linux Server (Remote SSH)

• Claude Code CLI: v2.0.72
• VS Code Extension: v2.0.72
• Platform: Linux (Ubuntu 24.04) x86_64
• Connection: VS Code Remote SSH

Machine 2: MacBook (Local)

• Claude Code CLI: v2.0.72
• VS Code Extension: v2.0.72
• Platform: macOS (Apple Silicon)
• Connection: Local (no remote)

---

Additional Context

• The 7.5-second delay appears to be the normal WebSocket connection establishment time
• Issue #8041 mentions status changing from "disconnected" to "connected" — some users DO see the transition
• In my testing, the indicator just disappears rather than showing "connected"
• This inconsistency adds to the confusion

---

_{🤖 Cross-platform UX testing (macOS + Linux) performed December 18, 2025}