Add configurable keyboard shortcuts system #252
Description
Summary
Implement a configurable keyboard shortcuts system that allows users to customize key bindings for various application functions, starting with permission mode cycling and expandable to other shortcuts.
Background
Currently, the application has limited keyboard shortcuts:
Enter: Submit message (configurable via enter behavior setting)Shift+Enter: Alternative behavior (newline/submit)Escape: Abort current request
Users have requested more keyboard shortcuts, particularly for permission mode cycling. A configurable system would provide flexibility and accommodate different user preferences and platform conflicts.
Proposed Implementation
Keyboard Shortcuts Management
- Configurable shortcuts section in unified settings page (requires Add unified settings page with theme and enter behavior integration #250)
- Default shortcuts with platform-specific variations (Ctrl vs Cmd)
- Conflict detection and warning system
- Shortcut validation and normalization
Initial Shortcuts to Implement
- Permission Mode Toggle:
Ctrl+Shift+M(Windows/Linux) /Cmd+Shift+M(macOS) - Abort Request:
Escape(existing, but now configurable) - Submit Message: Configurable alternative to Enter behavior
- Extensible for future shortcuts
Technical Architecture
- Keyboard event handling system with IME awareness
- Shortcut registration and dispatch system
- Platform detection for appropriate default shortcuts
- Settings integration with localStorage persistence
UI Components
- Keyboard shortcut input fields with live capture
- Conflict detection with visual warnings
- Shortcut display with platform-appropriate key symbols
- Help/reference panel for all available shortcuts
Technical Details
Settings Structure
interface AppSettings {
// existing settings...
keyboardShortcuts: {
permissionModeToggle: string; // "Ctrl+Shift+M"
abortRequest: string; // "Escape"
submitMessage: string; // "Enter"
// Future shortcuts...
};
}Shortcut Format
- Use standard format:
"Ctrl+Shift+M","Alt+Tab", etc. - Platform normalization:
"Cmd+Shift+M"on macOS - Single key support:
"Escape","F1", etc.
Event Handling
- Global keyboard event listener with proper cleanup
- Respect IME composition state (
isComposing) - Context-aware shortcuts (different behavior in different UI areas)
- Prevent conflicts with browser/system shortcuts
User Experience
Shortcut Configuration
- Settings panel with shortcut input fields
- Click field → press desired key combination → automatically captures
- Visual feedback for conflicts or invalid combinations
- Reset to defaults option
Help System
- Tooltip on permission mode indicator showing current shortcut
- Keyboard shortcuts help panel/modal
- Context-sensitive help (show relevant shortcuts based on current UI state)
Implementation Priority
Phase 1: Core Infrastructure
- Keyboard event handling system
- Settings integration
- Basic shortcut registration/dispatch
Phase 2: Permission Mode Toggle
- Implement permission mode cycling shortcut
- Update permission mode UI with shortcut indication
- Handle IME and focus state properly
Phase 3: Configurability
- Shortcut configuration UI in settings
- Conflict detection system
- Help/reference system
Acceptance Criteria
- Keyboard shortcuts section in unified settings page
- Default shortcut for permission mode toggle (Ctrl+Shift+M / Cmd+Shift+M)
- Shortcut configuration UI with live key capture
- Conflict detection warns users of duplicate shortcuts
- Platform-appropriate default shortcuts (Ctrl vs Cmd)
- IME composition state respected (no shortcuts during text input)
- Shortcuts work when textarea is focused
- Visual indication of current shortcuts in relevant UI elements
- Shortcut settings persisted in localStorage
- Help/reference panel for viewing all shortcuts
Dependencies
- Requires: Add unified settings page with theme and enter behavior integration #250 (unified settings page) to be completed first
- Related: Add keyboard shortcut for permission mode cycling #249 (permission mode cycling shortcut) - this system will address that request
Future Enhancements
- Project-specific shortcut overrides
- Shortcut profiles/presets
- Import/export shortcut configurations
- More application shortcuts (focus chat input, clear messages, etc.)
🤖 Generated with Claude Code