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

> Master Local-Deep-Research web interface keyboard shortcuts. Learn Enter, Esc, /, Ctrl+Enter, and Ctrl+S to boost your research workflow efficiency. Explore the complete guide.

- Repository: [learningcircuit/local-deep-research](https://github.com/learningcircuit/local-deep-research)
- Tags: how-to-guide
- Published: 2026-03-05

---

**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`](https://github.com/learningcircuit/local-deep-research/blob/main/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`](https://github.com/learningcircuit/local-deep-research/blob/main/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`](https://github.com/learningcircuit/local-deep-research/blob/main/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.

```javascript
// 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`](https://github.com/learningcircuit/local-deep-research/blob/main/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`](https://github.com/learningcircuit/local-deep-research/blob/main/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.

```javascript
// 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`](https://github.com/learningcircuit/local-deep-research/blob/main/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`](https://github.com/learningcircuit/local-deep-research/blob/main/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`](https://github.com/learningcircuit/local-deep-research/blob/main/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`](https://github.com/learningcircuit/local-deep-research/blob/main/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.