[BUG] ESC Key Causes Complete Terminal Freeze in Claude Code

[pm0code]

Summary

Pressing the ESC key during any Claude Code session causes the entire terminal to become unresponsive, requiring forced termination and resulting in complete loss of work.

Severity: CRITICAL 🔴

Environment Details (from /doctor diagnostic)

• Claude CLI Version: 1.0.63 (npm-local)
• Node.js: v22.17.1
• Path: /home/user/.nvm/versions/node/v22.17.1/bin/node
• Installation: /home/user/.claude/local/node_modules/.bin/claude
• Config Method: local
• Auto-updates: enabled
• Platform: Linux WSL2 (6.6.87.2-microsoft-standard-WSL2)
• Terminal: xterm-256color
• System: Intel Core i9-14900K, 63.8GB RAM

Steps to Reproduce

1. Start Claude Code: claude
2. Begin any normal workflow (editing files, running commands)
3. Press ESC key at any point
4. Terminal immediately becomes frozen:
   • No keyboard input accepted
   • No cursor movement
   • No response to Ctrl+C, Ctrl+D, Ctrl+Z
   • Only solution: Force close terminal window

Expected Behavior

• ESC should exit current mode gracefully OR
• ESC should be ignored if not in a specific mode OR
• Provide option to remap/disable ESC key

Actual Behavior

• Complete terminal freeze
• Loss of all unsaved work
• No recovery possible

Impact

• Data Loss: All session progress lost
• Productivity: Complete restart required
• User Trust: Critical usability issue

Diagnostic Findings

1. No Debug Logging: Claude Code has no built-in logging mechanism
2. No Crash Logs: No error logs generated in:
   • ~/.claude/
   • System logs (journalctl)
   • WSL logs
3. Process State: Multiple Claude processes remain running but unresponsive
4. Terminal Mode: Likely issue with terminal raw mode handling

Attempted Workarounds (All Failed)

• Setting CLAUDE_DEBUG=1
• Setting CLAUDE_LOG_LEVEL=debug
• Looking for verbose/debug flags
• Checking for log files

Root Cause Analysis

Likely terminal mode handling issue where:

1. Claude enters raw/alternative terminal mode
2. ESC key triggers undefined state transition
3. Terminal mode not properly restored
4. Input handling loop becomes stuck

Recommendations

1. Immediate: Add ESC key handling to prevent freeze
2. Short-term: Implement debug logging for terminal issues
3. Long-term: Add configurable key bindings
4. Critical: Add graceful recovery mechanism

Additional Context

• Issue persists across multiple sessions
• Affects WSL2 environment specifically
• No workaround currently exists
• Forces users to avoid ESC key entirely

Priority: P0 - CRITICAL

This is a data loss bug that makes Claude Code unusable for users who habitually use ESC key (vim users, terminal power users).