Keyboard Shortcuts in the Local-Deep-Research Web Interface: A Complete Guide

The Local-Deep-Research web interface provides five primary keyboard shortcuts: Enter to submit queries, Esc to close modals, / to focus the search box, Ctrl+Enter (⌘+Enter on macOS) to run benchmarks, and Ctrl+S (⌘+S) to save sessions.

The Local-Deep-Research project implements a lightweight, centralized keyboard shortcut registry designed to enhance productivity without interfering with text input. All shortcuts are defined in the keyboard.js service and selectively registered by individual page components to provide both global and context-specific functionality.

Global Keyboard Shortcuts

The system registers three global keyboard shortcuts in src/local_deep_research/web/static/js/services/keyboard.js (around line 101) that remain active across all pages.

Enter to Submit

Pressing Enter without modifiers submits the current query or activates the primary button when focused. The registry listens for the keydown event and triggers the default action of the focused element or the page's primary submission handler.

Esc to Dismiss

Pressing Esc closes any open modal, dropdown, or side-panel. When no modal is active and the user is not inside a text input, Esc also clears the search field to allow quick reset of the current query.

Forward Slash for Search

Pressing / (forward slash) immediately moves focus to the main search textbox. This allows users to start typing a new query without manually clicking the input field, similar to patterns found in modern web applications like Gmail or GitHub.

Research Editor Shortcuts

The research component located at src/local_deep_research/web/static/js/components/research.js (around line 642) registers page-specific shortcuts that only activate when the editor has focus.

Run Benchmark or Optimization

Pressing Ctrl+Enter on Windows/Linux or ⌘+Enter on macOS triggers the "run-benchmark" or "run-optimization" action from the toolbar. This shortcut allows power users to execute research workflows without removing their hands from the keyboard.

Save Current Session

Pressing Ctrl+S (or ⌘+S on macOS) saves the current research session to local storage. This prevents accidental loss of work and provides instant persistence without navigating through file menus.

// Page-specific registration in research.js
KeyboardShortcuts.register('runBenchmark', {
  keys: [{ key: 'Enter', ctrlKey: true }],   // Ctrl+Enter
  handler: () => runBenchmark(),
});
KeyboardShortcuts.register('saveSession', {
  keys: [{ key: 's', ctrlKey: true }],      // Ctrl+S
  handler: () => saveCurrentSession(),
});

Navigation and List Shortcuts

While not explicitly registered in the central keyboard.js file, the interface supports standard navigation patterns through browser-native behavior and component-specific handlers.

Tab and Shift+Tab

Tab and Shift+Tab navigate between interactive elements including buttons, inputs, and menus. The shortcut registry deliberately ignores these keys to preserve standard browser focus management, ensuring compatibility with screen readers and accessibility tools.

Arrow Keys for Lists

The arrow keys (← ↑ → ↓) navigate through autocomplete suggestions, result lists, and history panels. This functionality is implemented in individual UI components such as the progress component at src/local_deep_research/web/static/js/components/progress.js, which handles list navigation when those elements have focus.

How the Shortcut Registry Works

The keyboard shortcut registry prevents conflicts between application shortcuts and regular text input. Before executing any registered handler, the system checks whether the active element is a text field.

// Excerpt from keyboard.js initialization
function initKeyboardShortcuts() {
  document.addEventListener('keydown', (event) => {
    // Skip shortcuts when typing, except navigation shortcuts and Esc
    const activeEl = document.activeElement;
    const isInput = activeEl && ['INPUT', 'TEXTAREA'].includes(activeEl.tagName);
    if (isInput && !isNavShortcut(event) && event.key !== 'Escape') return;

    // Iterate over registered shortcuts and invoke matching handler
    for (const [name, shortcut] of Object.entries(shortcuts)) {
      for (const pattern of shortcut.keys) {
        if (matchesPattern(event, pattern)) {
          shortcut.handler(event);
          event.preventDefault();
          break;
        }
      }
    }
  });
}

This logic ensures that pressing / while typing in a text field inserts the character rather than jumping to the search box, while still allowing Esc to close modals even when inputs are focused.

Testing and Accessibility

The project maintains automated tests in tests/ui_tests/test_keyboard_accessibility_ci.js to verify that all keyboard shortcuts are documented and behave as expected. These tests assert that:

• Shortcuts do not fire when users are typing in input fields (with specific exceptions for Esc and navigation)
• Platform-specific modifiers (Ctrl vs ⌘) are correctly mapped
• All registered shortcuts have corresponding handler functions

The lightweight registry approach ensures that the interface remains fully operable via keyboard, supporting both power users and those who rely on assistive technologies.

Summary

• Enter submits queries and activates primary buttons globally
• Esc closes modals, dropdowns, and clears search fields
• / (forward slash) focuses the main search input immediately
• Ctrl+Enter (or ⌘+Enter) runs benchmarks from the research editor
• Ctrl+S (or ⌘+S) saves the current research session to local storage
• The registry in keyboard.js filters shortcuts when typing in inputs to prevent accidental triggers
• Navigation via Tab and arrow keys preserves native browser behavior

Frequently Asked Questions

How do I disable keyboard shortcuts while typing?

You do not need to manually disable shortcuts. The registry automatically detects when you are focused on an INPUT or TEXTAREA element and suppresses all shortcuts except Esc and navigation keys. This logic is implemented in src/local_deep_research/web/static/js/services/keyboard.js within the initKeyboardShortcuts function.

Do the keyboard shortcuts work on macOS?

Yes, the shortcuts support platform-specific modifiers. While the code registers shortcuts using ctrlKey: true, modern browsers on macOS automatically map Ctrl+Enter to ⌘+Enter and Ctrl+S to ⌘+S based on the KeyboardShortcuts service configuration in the research component.

Where can I add custom keyboard shortcuts to the interface?

To add new shortcuts, import the KeyboardShortcuts service in your component file and call KeyboardShortcuts.register() with a unique name, key pattern, and handler function. Follow the pattern shown in src/local_deep_research/web/static/js/components/research.js around line 642 to ensure consistent behavior across the application.

Why doesn't the / shortcut work when I'm editing text?

This is intentional design behavior. The forward slash shortcut only activates when you are not focused on a text input field. If you are typing in a search box, textarea, or any input element, pressing / will insert the character normally. This prevents disruption when entering queries that contain the slash character.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}