Command Palette & Deep Links
Relevant source files
The following files were used as context for generating this wiki page:
The Command Palette and Deep Linking systems in Linux Archductor provide a unified navigation and execution interface for the application. The Command Palette allows users to search and trigger global actions, navigate between application pages, and execute repository-specific terminal commands via a centralized modal. This is complemented by the Deep Link system, which enables external invocation of specific application states—such as opening a specific workspace tab—using a custom URI scheme.
These systems are integrated into the GTK application shell, leveraging the repository's customization engine to provide dynamic, context-aware actions based on the currently selected workspace and user-defined keybindings.
Command Palette Architecture
The Command Palette is implemented as a transient modal dialog triggered by global shortcuts (default Ctrl+K). It aggregates commands from multiple sources: global navigation, workspace-specific tabs, and user-defined presets found in repository settings.
Core Data Structures
The system uses the PaletteCommand struct to represent an executable action within the palette. Each command maps to a PaletteTarget, which defines the execution logic.
| Structure | Description |
|---|---|
PaletteCommand | Contains a label, an optional shortcut display string, and a PaletteTarget. |
PaletteTarget | An enum representing targets: Page, WorkspaceTab, Refresh, ToggleSidebar, or RunCommand. |
Keybindings | Stores the mapping of physical keys to application actions, including custom tab navigation. |
Sources: crates/gtk-app/src/command_palette.rs:36-55, crates/gtk-app/src/command_palette.rs:8-34
Command Generation and Filtering
Commands are generated dynamically based on the application state. If a workspace is active, the palette extends its list to include workspace-specific tabs (e.g., Changes, Checks, Review) and custom command presets.
Customization and Keybindings
Users can customize Command Palette behavior and global shortcuts through repository settings (.archductor/settings.toml).
Keybinding Configuration
The Keybindings system supports presets like vim (which changes the palette shortcut to Ctrl+P) and granular action=shortcut mappings. Supported actions include:
palette: Open the command palette.refresh: Refresh the application state.sidebar: Toggle the sidebar visibility.changes/checks/review/chat/terminal: Navigate directly to workspace tabs.
Sources: crates/gtk-app/src/command_palette.rs:70-110, README.md:280-288
Command Presets
Repository-specific commands can be added to the palette using command_palette_presets. These appear as RunCommand targets.
- Aliases:
test,lint,build,ci,status,diff. - Custom Mapping:
Label=commandorLabel: commandsyntax.
Sources: crates/gtk-app/src/command_palette.rs:253-294, README.md:290-305
Deep Linking System
Linux Archductor registers a custom URI scheme, linux-archductor://, allowing external tools or scripts to control the application state.
URI Parsing Logic
The LaunchTarget struct is derived from the URI components. The system supports navigating to specific pages and deep-linking into specific workspaces and tabs.
| URI Format | Resulting Action |
|---|---|
linux-archductor://dashboard | Navigates to the Dashboard page. |
linux-archductor://workspace/{name} | Opens the specified workspace. |
linux-archductor://workspace/{name}?tab=checks | Opens the workspace and focuses the "Checks" tab. |
linux-archductor://history | Navigates to the History page. |
Sources: crates/gtk-app/src/main.rs:200-244, crates/gtk-app/src/main.rs:163-198
Sequence: Processing a Deep Link
The following diagram illustrates how the application processes a deep link URI during runtime or startup.
UI Integration
The Command Palette is rendered as a modal using render_command_palette_results. It utilizes a fuzzy matching approach where search terms include the command label, its shortcut, and various workflow keywords (e.g., searching "ci" will match the "Checks" tab).
Execution Flow
When a palette target is applied via apply_palette_target:
- Pages: The
AppStateis updated, and the main GTKStackswitches views. - Workspace Tabs: The app ensures the "workspace" page is visible and focuses the correct inner tab.
- RunCommand: The system opens the workspace database, retrieves the terminal command, and executes it within the active workspace context.
- UI Actions: Triggers immediate actions like
RefreshScope::Allor sidebar toggling.
Sources: crates/gtk-app/src/main.rs:806-832, crates/gtk-app/src/main.rs:857-890
Conclusion
The Command Palette and Deep Linking systems provide a robust navigation layer for Linux Archductor. By combining a searchable global action interface with a programmable URI scheme, the application ensures that both interactive users and automated workflows can efficiently access specific workspace states and repository tools. The tight integration with the repository customization model allows these interfaces to evolve alongside the project's configuration.