Command Palette & Global Shortcuts
Relevant source files
The following files were used as context for generating this wiki page:
The Command Palette and Global Shortcuts system provides a centralized interface for workspace navigation, command execution, and project management. It acts as a global launcher that integrates project switching, terminal actions, and tool configuration into a single keyboard-driven workflow.
This system ensures high productivity by mapping complex operations to simple keybindings and a searchable command interface. It maintains platform parity between Tauri desktop environments and web clients while adapting the user interface for mobile ergonomics.
Sources: README.md:95-99, src/renderer/components/CommandPalette.tsx:114-120
Command Palette Architecture
The CommandPalette component is a modal interface built using the cmdk library. It organizes available actions into logical categories and provides real-time filtering based on user input.
Command Definition and Categorization
Commands are defined using the CommandDef interface, which encapsulates the execution logic, display metadata, and searchable keywords. The palette groups these definitions into four primary categories:
| Category | Purpose |
|---|---|
| Projects | Switches the active workspace to a specific project. |
| Workspace | Manages terminals, browser tabs, and snapshots. |
| Navigation | Accesses project settings and global app preferences. |
| Tools | Opens command history, theme pickers, and shortcut menus. |
Sources: src/renderer/components/CommandPalette.tsx:48-66, src/renderer/components/CommandPalette.test.tsx:102-110
Logic and Data Flow
The palette integrates with several custom hooks to manage state and persistence. It tracks recent commands to provide quick access and allows users to pin frequently used actions.
Execution and Persistence
When a user selects a command, the executeCommand function triggers the associated callback and persists the command ID to the recent commands list.
- Recent Commands: The system records the ID of executed commands to populate a "Recent" group when the search query is empty.
- Pinned Commands: Users can toggle a pin status for any command. Pinned commands appear at the top of the list for immediate access.
- Error Handling: Persistence failures for recent or pinned commands are logged as warnings, but the system does not block the primary action from executing.
Sources: src/renderer/components/CommandPalette.tsx:290-318, src/renderer/components/CommandPalette.test.tsx:244-258
Global Shortcuts and Keyboard API
The keyboard system relies on a platform-adaptive API bridge to handle global hotkeys. The keyboardApi manages shortcut registrations, while the Keyboard domain in the parity checklist ensures desktop and web consistency.
Keybinding Resolution
The WorkspaceLayout component subscribes to global shortcuts and maps them to internal actions. Desktop-reserved shortcuts (like Ctrl+Tab on some browsers) are avoided to ensure reliability across environments.
| Action | Default Shortcut | Implementation Source |
|---|---|---|
| Command Palette | Ctrl+K / Ctrl+Shift+P | keyboard-shortcuts-store |
| New Terminal | Ctrl+T | terminal-store |
| Next Tab | Ctrl+PageDown | workspace-store |
| Previous Tab | Ctrl+PageUp | workspace-store |
Sources: README.md:195-201, src/renderer/layouts/WorkspaceLayout.test.tsx:143-162, src/renderer/lib/tests/parity-checklist.test.ts:153-159
Shortcut Execution Flow
The following sequence describes how a global shortcut is processed through the renderer:
Platform Parity and Adaptation
The system adapts behavior based on the execution context (Tauri Desktop vs. Web) and the device type.
Desktop vs. Web Parity
Certain commands, such as "New Browser Tab," are restricted to the Tauri desktop environment because they rely on native webview capabilities not available in a standard browser client. The parity checklist enforces that the keyboardApi implements onShortcut across all adapters.
Sources: src/renderer/components/CommandPalette.test.tsx:205-214, src/renderer/lib/tests/parity-checklist.test.ts:153-159
Mobile Ergonomics
On mobile web shells, the Command Palette undergoes structural changes to improve usability:
- Positioning: The palette is anchored to the lower third of the screen (the "thumb zone") instead of the top.
- Visual Controls: Keyboard hints (↑↓/↵/Esc) are hidden, and a large, touch-sized close button is added.
- Safe Areas: The layout respects
env(safe-area-inset-bottom)to avoid overlap with system home indicators.
Sources: src/renderer/components/CommandPalette.tsx:406-414, src/renderer/components/CommandPalette.test.tsx:273-288
Summary
The Command Palette and Global Shortcuts system provides a unified entry point for all major Termul operations. By combining a searchable command interface with persistent user preferences and platform-aware API bridges, the system delivers a consistent experience across desktop, web, and mobile surfaces. It prioritizes keyboard efficiency while maintaining fallback accessibility for touch-based interfaces.
Sources: README.md:95-99, src/renderer/components/CommandPalette.tsx:440-455