# How Keyboard Shortcuts Are Registered and Managed Globally in TUUI

> Discover how TUUI registers and manages global keyboard shortcuts using Electron's globalShortcut API in its main process for efficient hotkey handling.

- Repository: [AIQL/tuui](https://github.com/ai-ql/tuui)
- Tags: internals
- Published: 2026-02-23

---

**TUUI uses Electron's `globalShortcut` API to register application-wide hotkeys through a centralized system in the main process that unregisters old bindings, loads user configuration, and registers new accelerators on every application start.**

TUUI implements a robust global keyboard shortcut system that allows users to trigger actions even when the application window is not focused. This article examines how the Electron-based application registers and manages these shortcuts globally using a centralized configuration and registration pipeline defined in the main process.

## Understanding TUUI's Global Shortcut Architecture

TUUI's shortcut system is split into three tightly-coupled layers that handle configuration, accelerator construction, and runtime registration.

### Configuration and Default Shortcuts

The foundation of the system lives in [`src/main/aid/config.ts`](https://github.com/ai-ql/tuui/blob/main/src/main/aid/config.ts), which defines the **Shortcut** type and supplies default keybindings through `loadSettings()`. The configuration object specifies modifier keys (`alt`, `ctrl`, `shift`, `meta`) and the primary `key`.

By default, TUUI ships with `Ctrl+Alt+T` bound to the *command* action:

```typescript
// src/main/aid/config.ts
export interface Shortcut {
  alt?: boolean;
  ctrl?: boolean;
  shift?: boolean;
  meta?: boolean;
  key: string;
}

export const loadSettings = (): Configuration => ({
  shortcuts: {
    command: {
      key: 'T',
      ctrl: true,
      alt: true
    }
  }
});

```

### Accelerator Construction and Registration

The [`src/main/aid/shortcuts.ts`](https://github.com/ai-ql/tuui/blob/main/src/main/aid/shortcuts.ts) file handles the conversion of configuration objects into Electron-compatible accelerator strings and manages the lifecycle of global registrations.

The `shortcutAccelerator()` function transforms a **Shortcut** object into the format Electron expects (e.g., `Alt+Control+T`):

```typescript
// src/main/aid/shortcuts.ts
const shortcutAccelerator = (shortcut: Shortcut): string => {
  const parts: string[] = [];
  if (shortcut.ctrl) parts.push('Control');
  if (shortcut.alt) parts.push('Alt');
  if (shortcut.shift) parts.push('Shift');
  if (shortcut.meta) parts.push('Command');
  parts.push(shortcut.key.toUpperCase());
  return parts.join('+');
};

```

The private `registerShortcut()` method then binds this accelerator using `globalShortcut.register()`:

```typescript
// src/main/aid/shortcuts.ts
const registerShortcut = (
  shortcut: Shortcut,
  callback: () => void
): boolean => {
  const accelerator = shortcutAccelerator(shortcut);
  return globalShortcut.register(accelerator, callback);
};

```

### Application Bootstrap Process

The registration pipeline is triggered when Electron's `app` emits the **`ready`** event. In [`src/main/index.ts`](https://github.com/ai-ql/tuui/blob/main/src/main/index.ts), TUUI initializes the Commander subsystem before calling `registerShortcuts()` to ensure all dependencies are ready:

```typescript
// src/main/index.ts
import { shortcuts } from './aid/shortcuts';
import { Commander } from './aid/commander';

const registerShortcuts = async () => {
  const initState = await Commander.init();
  if (initState) {
    shortcuts.registerShortcuts({
      command: () => Commander.initCommand()
    });
  }
};

app.whenReady().then(() => {
  // ... window creation logic
  registerShortcuts();
});

```

Because registration occurs in the **main process**, shortcuts remain active even when no renderer window is focused, which is essential for a desktop assistant like TUUI.

## Step-by-Step Registration Flow

When TUUI registers and manages global keyboard shortcuts, it follows this deterministic pipeline:

1. **Clear existing bindings** – `registerShortcuts()` calls `globalShortcut.unregisterAll()` to prevent duplicate registrations.
2. **Load configuration** – `loadSettings()` retrieves the current shortcut map from [`config.ts`](https://github.com/ai-ql/tuui/blob/main/config.ts).
3. **Build accelerators** – `shortcutAccelerator()` converts each shortcut object into an Electron-compatible string.
4. **Register with Electron** – `globalShortcut.register(accelerator, callback)` binds each hotkey to its handler.
5. **Delegate to business logic** – Callbacks route to `Commander.initCommand()` or other handlers defined in the bootstrap.

This reload-safe design allows TUUI to update shortcuts at runtime by simply re-invoking `registerShortcuts()` after configuration changes.

## Customizing Global Keyboard Shortcuts in TUUI

To add or modify global keyboard shortcuts in TUUI, you must update both the configuration schema and the registration call.

**Example: Adding a "Show Help" shortcut (`Ctrl+H`):**

First, extend the types in [`src/main/aid/config.ts`](https://github.com/ai-ql/tuui/blob/main/src/main/aid/config.ts):

```typescript
export type ShortcutsConfig = {
  command: Shortcut;
  help: Shortcut;  // New entry
};

export const loadSettings = (): Configuration => ({
  shortcuts: {
    command: { key: 'T', ctrl: true, alt: true },
    help: { key: 'H', ctrl: true }  // Ctrl+H
  }
});

```

Then, update the bootstrap in [`src/main/index.ts`](https://github.com/ai-ql/tuui/blob/main/src/main/index.ts):

```typescript
shortcuts.registerShortcuts({
  command: () => Commander.initCommand(),
  help: () => Commander.showHelp()  // Your custom handler
});

```

The existing pipeline in [`shortcuts.ts`](https://github.com/ai-ql/tuui/blob/main/shortcuts.ts) automatically handles the new shortcut without further modifications.

## Summary

- TUUI registers global keyboard shortcuts using Electron's **`globalShortcut`** API in the main process.
- Configuration lives in **[`src/main/aid/config.ts`](https://github.com/ai-ql/tuui/blob/main/src/main/aid/config.ts)**, defining the `Shortcut` type and default keybindings like `Ctrl+Alt+T`.
- **[`src/main/aid/shortcuts.ts`](https://github.com/ai-ql/tuui/blob/main/src/main/aid/shortcuts.ts)** converts shortcuts to accelerators and manages registration lifecycle via `registerShortcuts()`, `shortcutAccelerator()`, and `globalShortcut.register()`.
- The system calls **`globalShortcut.unregisterAll()`** before registering new shortcuts to prevent duplicates and enable runtime updates.
- Registration occurs in **[`src/main/index.ts`](https://github.com/ai-ql/tuui/blob/main/src/main/index.ts)** when the `app.ready` event fires, ensuring shortcuts work globally even without a focused window.

## Frequently Asked Questions

### What Electron API does TUUI use for global keyboard shortcuts?

TUUI uses the **`globalShortcut`** module from Electron's main process API. Specifically, it calls `globalShortcut.register()` to bind accelerators and `globalShortcut.unregisterAll()` to clear existing bindings before reloading configuration. This API allows the application to listen for keyboard events even when the application does not have keyboard focus.

### Where are the default keyboard shortcuts defined in TUUI?

Default shortcuts are defined in **[`src/main/aid/config.ts`](https://github.com/ai-ql/tuui/blob/main/src/main/aid/config.ts)** within the `loadSettings()` function. The default configuration includes a `command` shortcut mapped to `Ctrl+Alt+T` (represented as `{ key: 'T', ctrl: true, alt: true }`). This file also exports the `Shortcut` interface that defines the shape of all shortcut objects used throughout the application.

### Can I register multiple global shortcuts in TUUI?

Yes, you can register multiple shortcuts by extending the `ShortcutsConfig` type in [`src/main/aid/config.ts`](https://github.com/ai-ql/tuui/blob/main/src/main/aid/config.ts) to include additional shortcut keys, providing default values in `loadSettings()`, and passing corresponding callback functions to `shortcuts.registerShortcuts()` in [`src/main/index.ts`](https://github.com/ai-ql/tuui/blob/main/src/main/index.ts). The existing registration pipeline automatically iterates over all defined shortcuts and registers each with Electron's `globalShortcut` module.

### Why do TUUI shortcuts work even when the window is not focused?

TUUI shortcuts work globally because they are registered in Electron's **main process** using the `globalShortcut` API, which operates at the operating system level rather than the renderer level. Unlike renderer-process keyboard listeners that require window focus, `globalShortcut` registers system-wide hotkeys that capture keystrokes regardless of which application currently has focus, which is essential for a desktop assistant utility.