[FEATURE] Extended Thinking Mode Keybinding Conflict and Custom Keybindings

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

The default meta+t (Command+T on macOS) keybinding for toggling extended thinking mode conflicts with iTerm's built-in "New Tab" shortcut. When attempting to use the extended thinking toggle in Claude Code running within iTerm, the terminal emulator intercepts the keybinding and opens a new tab instead, making the extended thinking feature effectively inaccessible via keyboard shortcut.

Custom keybindings appear to be implemented in Claude Code (configuration file format exists, schema is documented) but are currently disabled behind feature flags:

• tengu_keybinding_customization: false
• tengu_keybinding_customization_release: false

This prevents users from resolving keybinding conflicts by configuring alternative shortcuts.

Impact: Users cannot access extended thinking mode via keyboard when using popular terminal emulators (iTerm, and potentially others with similar default shortcuts).

Proposed Solution

Enable the custom keybindings feature by setting the feature flags to true in a stable release.

The implementation appears ready:

• Configuration file format exists (~/.claude/keybindings.json)
• JSON schema is documented and available
• Debug logs show the system detects and validates the configuration file
• The only blocker is the feature flag check

Benefits:

• Users can resolve keybinding conflicts with their terminal emulators
• Provides flexibility for different workflows and accessibility needs
• Empowers users to customize their development environment
• Minimal risk since the infrastructure is already implemented

Alternative Solutions

If enabling custom keybindings cannot be done immediately, consider these alternatives:

Option A: Change the Default Keybinding

Change the default extended thinking toggle from meta+t to a keybinding that doesn't conflict with common terminal emulator shortcuts:

Suggested alternatives:

• meta+shift+e (Command+Shift+E) - Less commonly used
• ctrl+alt+t (Ctrl+Alt+T) - Multi-modifier reduces conflicts
• meta+option+t (Command+Option+T on macOS) - Terminal-safe
• meta+; (Command+;) - Punctuation keys have fewer conflicts

Option B: Provide Environment-Specific Defaults

Detect when Claude Code is running in a terminal emulator and automatically use a different default keybinding for those environments.

Option C: Document the Tab Key Workaround

If Tab key toggling is available (suggested by tips history), document this clearly as the primary method until custom keybindings are enabled.

Priority

Medium - Would be very helpful

Feature Category

CLI commands and flags

Use Case Example

Current Broken Workflow

User: macOS developer using iTerm with Claude Code

Scenario: Working on a complex refactoring task that benefits from extended thinking mode

Steps:

1. User types a question into Claude Code chat
2. User presses Command+T to enable extended thinking mode
3. iTerm intercepts the keybinding and opens a new terminal tab
4. User's Claude Code session is now in a background tab
5. Extended thinking mode was never toggled

Result: User cannot access extended thinking mode via keyboard and must either:

• Use mouse/trackpad to click UI elements (if available)
• Reconfigure iTerm shortcuts (breaks muscle memory for other terminal use)
• Go without extended thinking mode

Desired Workflow with Custom Keybindings

Configuration (~/.claude/keybindings.json):

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "meta+t": null,
        "ctrl+shift+t": "chat:thinkingToggle"
      }
    }
  ]
}

Steps:

1. User types a question into Claude Code chat
2. User presses Ctrl+Shift+T (custom keybinding)
3. Extended thinking mode toggles successfully
4. Visual indicator confirms the mode change
5. User continues working efficiently

Result: Seamless keyboard-driven workflow without terminal emulator conflicts.

Additional Context

Environment

• Claude Code Version: 2.1.29 (latest as of 2026-02-02)
• OS: macOS (Darwin 25.2.0)
• Terminal: iTerm
• Installation Method: Native
• Updates: Auto-updates disabled (common in enterprise environments)

Investigation Details

Created a properly structured ~/.claude/keybindings.json file following the documented schema:

{
  "$schema": "https://platform.claude.com/docs/schemas/claude-code/keybindings.json",
  "$docs": "https://code.claude.com/docs/en/keybindings",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "meta+t": null,
        "ctrl+shift+t": "chat:thinkingToggle"
      }
    }
  ]
}

Debug logs confirm the file is detected but ignored:

2026-02-02T12:04:05.562Z [DEBUG] [keybindings] KeybindingSetup initialized with 99 bindings, 0 warnings
2026-02-02T12:04:05.589Z [DEBUG] [keybindings] Skipping file watcher - user customization disabled

Feature flags in ~/.claude.json:

{
  "cachedGrowthBookFeatures": {
    "tengu_keybinding_customization": false,
    "tengu_keybinding_customization_release": false
  }
}

Attempted Workarounds

1. ✗ Tried meta+shift+t - Still conflicts with iTerm
2. ✗ Tried ctrl+shift+t - Configuration ignored due to feature flag
3. ✗ Attempted to add customization.enabled to settings.local.json - Rejected by schema validation
4. ? Tab key toggle mentioned in tips - Not clearly documented

Common Terminal Emulators Affected

This issue likely affects multiple terminal emulators with similar default shortcuts:

• iTerm: Command+T for new tab (macOS)
• Terminal.app: Command+T for new tab (macOS)
• Kitty: May have similar conflicts
• Alacritty: Depends on user configuration

Questions for Maintainers

1. Timeline: Is there a planned release date for enabling the custom keybindings feature?
2. Early Access: Can this feature be enabled for users experiencing conflicts?
3. Workaround: What is the official recommended workaround for the Command+T conflict?
4. Tab Toggle: Is the Tab key toggle the same as chat:thinkingToggle? Is it documented?
5. Enterprise: Will this feature be available to enterprise/managed installations?

Technical Notes

• Configuration file structure is valid and follows the documented schema
• No JSON validation errors or file permission issues
• Feature appears fully implemented but gated behind server-side feature flags
• The system successfully validates the keybindings file before checking the feature flag
• Once enabled, the feature should work immediately without code changes

---

Thank you for considering this request! Custom keybindings would significantly improve the Claude Code experience for terminal-based workflows, especially for users in terminal emulators with conflicting default shortcuts.