# pqrs-org/karabiner-elements architecture

> Architecture diagram of the GitHub repository pqrs-org/karabiner-elements, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pqrs-org/karabiner-elements
- Repository: https://github.com/pqrs-org/karabiner-elements

## Overview

Karabiner-Elements is a macOS key-remapping application. Its principal workflow is configuring device- or profile-specific modifications, then processing input events through manipulators and sending resulting events to virtual HID devices. Supporting branches cover device capture, settings and service coordination, and event inspection. The README establishes the product purpose; source-index references and excerpts support the cited internal links. Several runtime connections are not shown in the sampled sources, so those links are omitted or marked unverified.

Main entry points: [`src/share/manipulator/manipulator_manager.hpp`](https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/manipulator/manipulator_manager.hpp) (Manipulator manager), [`src/share/core_service_daemon_client.hpp`](https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/core_service_daemon_client.hpp) (Core service client), [`src/apps/ConsoleUserServer/include/console_user_server/components_manager.hpp`](https://github.com/pqrs-org/karabiner-elements/blob/main/src/apps/ConsoleUserServer/include/console_user_server/components_manager.hpp) (Console user server), [`src/apps/CoreService/include/core_service/daemon/components_manager.hpp`](https://github.com/pqrs-org/karabiner-elements/blob/main/src/apps/CoreService/include/core_service/daemon/components_manager.hpp) (Daemon components)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Configuration"]
  node_profiles["Profiles and rules<br/>[profile.hpp]"]
  node_configuration_data["Configuration model"]
  node_config_monitor["Configuration monitor"]
  node_assets["Modification assets"]
end

subgraph group_input["Input processing"]
  node_device_grabber["Device capture<br/>[device_grabber.hpp]"]
  node_event_queue["Event queue<br/>[queue.hpp]"]
  node_manipulator_manager["Manipulator manager"]
  node_manipulator_factory["Manipulator factory"]
  node_modifier_state["Modifier state"]
  node_virtual_hid["Virtual HID output"]
end

subgraph group_services["Background services"]
  node_daemon["Core service<br/>[main.cpp]"]
  node_daemon_components["Daemon components"]
  node_console_server["Console user server"]
  node_receiver["Command receiver<br/>[receiver.hpp]"]
end

subgraph group_apps["User applications"]
  node_settings["Settings UI<br/>[ContentView.swift]"]
  node_event_viewer["Event Viewer<br/>[ContentView.swift]"]
  node_cli["Command-line client<br/>[main.cpp]"]
end

subgraph group_shared["Shared runtime"]
  node_core_client["Core service client"]
  node_xpc["XPC transport<br/>[xpc_client.hpp]"]
end

node_user(("Mac user"))
node_application(("macOS input"))

node_user -.->|"configures"| node_settings
node_settings -.->|"edits"| node_profiles
node_profiles -.->|"defines"| node_configuration_data
node_config_monitor -->|"loads"| node_configuration_data
node_daemon_components -->|"observes"| node_config_monitor
node_settings -.->|"manages"| node_assets
node_application -.->|"provides input"| node_device_grabber
node_device_grabber -.->|"queues events"| node_event_queue
node_event_queue -->|"supplies events"| node_manipulator_manager
node_manipulator_manager -->|"uses factory"| node_manipulator_factory
node_manipulator_manager -.->|"updates state"| node_modifier_state
node_manipulator_manager -.->|"posts events"| node_virtual_hid
node_daemon -.->|"starts"| node_daemon_components
node_daemon_components -.->|"manages"| node_device_grabber
node_console_server -->|"observes"| node_config_monitor
node_console_server -->|"creates"| node_receiver
node_console_server -->|"notifies"| node_core_client
node_core_client -->|"transports requests"| node_xpc
node_event_viewer -.->|"queries service"| node_core_client
node_cli -->|"sends commands"| node_core_client

click node_settings "https://github.com/pqrs-org/karabiner-elements/blob/main/src/apps/SettingsWindow/src/View/ContentView.swift"
click node_profiles "https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/core_configuration/details/profile.hpp"
click node_configuration_data "https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/core_configuration/core_configuration.hpp"
click node_config_monitor "https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/monitor/configuration_monitor.hpp"
click node_assets "https://github.com/pqrs-org/karabiner-elements/blob/main/src/apps/SettingsWindow/src/cpp/settings_complex_modifications_assets_manager.hpp"
click node_daemon "https://github.com/pqrs-org/karabiner-elements/blob/main/src/apps/CoreService/src/main.cpp"
click node_daemon_components "https://github.com/pqrs-org/karabiner-elements/blob/main/src/apps/CoreService/include/core_service/daemon/components_manager.hpp"
click node_device_grabber "https://github.com/pqrs-org/karabiner-elements/blob/main/src/apps/CoreService/include/core_service/daemon/device_grabber.hpp"
click node_event_queue "https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/event_queue/queue.hpp"
click node_manipulator_manager "https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/manipulator/manipulator_manager.hpp"
click node_manipulator_factory "https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/manipulator/manipulator_factory.hpp"
click node_modifier_state "https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/modifier_flag_manager.hpp"
click node_virtual_hid "https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/virtual_hid_device_utility.hpp"
click node_console_server "https://github.com/pqrs-org/karabiner-elements/blob/main/src/apps/ConsoleUserServer/include/console_user_server/components_manager.hpp"
click node_receiver "https://github.com/pqrs-org/karabiner-elements/blob/main/src/apps/ConsoleUserServer/include/console_user_server/receiver.hpp"
click node_core_client "https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/core_service_daemon_client.hpp"
click node_xpc "https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/xpc_client.hpp"
click node_event_viewer "https://github.com/pqrs-org/karabiner-elements/blob/main/src/apps/EventViewer/src/View/ContentView.swift"
click node_cli "https://github.com/pqrs-org/karabiner-elements/blob/main/src/bin/cli/src/main.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_profiles,node_configuration_data,node_config_monitor,node_assets,node_user toneBlue
class node_device_grabber,node_event_queue,node_manipulator_manager,node_manipulator_factory,node_modifier_state,node_virtual_hid toneAmber
class node_daemon,node_daemon_components,node_console_server,node_receiver toneMint
class node_settings,node_event_viewer,node_cli toneRose
class node_core_client,node_xpc,node_application toneIndigo
```

## Components

### Configuration

- [Profiles and rules](https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/core_configuration/details/profile.hpp): `src/share/core_configuration/details/profile.hpp`
- [Configuration model](https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/core_configuration/core_configuration.hpp): `src/share/core_configuration/core_configuration.hpp`
- [Configuration monitor](https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/monitor/configuration_monitor.hpp): `src/share/monitor/configuration_monitor.hpp`
- [Modification assets](https://github.com/pqrs-org/karabiner-elements/blob/main/src/apps/SettingsWindow/src/cpp/settings_complex_modifications_assets_manager.hpp): `src/apps/SettingsWindow/src/cpp/settings_complex_modifications_assets_manager.hpp`

### Input processing

- [Device capture](https://github.com/pqrs-org/karabiner-elements/blob/main/src/apps/CoreService/include/core_service/daemon/device_grabber.hpp): `src/apps/CoreService/include/core_service/daemon/device_grabber.hpp`
- [Event queue](https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/event_queue/queue.hpp): `src/share/event_queue/queue.hpp`
- [Manipulator manager](https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/manipulator/manipulator_manager.hpp): `src/share/manipulator/manipulator_manager.hpp`
- [Manipulator factory](https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/manipulator/manipulator_factory.hpp): `src/share/manipulator/manipulator_factory.hpp`
- [Modifier state](https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/modifier_flag_manager.hpp): `src/share/modifier_flag_manager.hpp`
- [Virtual HID output](https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/virtual_hid_device_utility.hpp): `src/share/virtual_hid_device_utility.hpp`

### Background services

- [Core service](https://github.com/pqrs-org/karabiner-elements/blob/main/src/apps/CoreService/src/main.cpp): `src/apps/CoreService/src/main.cpp`
- [Daemon components](https://github.com/pqrs-org/karabiner-elements/blob/main/src/apps/CoreService/include/core_service/daemon/components_manager.hpp): `src/apps/CoreService/include/core_service/daemon/components_manager.hpp`
- [Console user server](https://github.com/pqrs-org/karabiner-elements/blob/main/src/apps/ConsoleUserServer/include/console_user_server/components_manager.hpp): `src/apps/ConsoleUserServer/include/console_user_server/components_manager.hpp`
- [Command receiver](https://github.com/pqrs-org/karabiner-elements/blob/main/src/apps/ConsoleUserServer/include/console_user_server/receiver.hpp): `src/apps/ConsoleUserServer/include/console_user_server/receiver.hpp`

### User applications

- [Settings UI](https://github.com/pqrs-org/karabiner-elements/blob/main/src/apps/SettingsWindow/src/View/ContentView.swift): `src/apps/SettingsWindow/src/View/ContentView.swift`
- [Event Viewer](https://github.com/pqrs-org/karabiner-elements/blob/main/src/apps/EventViewer/src/View/ContentView.swift): `src/apps/EventViewer/src/View/ContentView.swift`
- [Command-line client](https://github.com/pqrs-org/karabiner-elements/blob/main/src/bin/cli/src/main.cpp): `src/bin/cli/src/main.cpp`

### Shared runtime

- [Core service client](https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/core_service_daemon_client.hpp): `src/share/core_service_daemon_client.hpp`
- [XPC transport](https://github.com/pqrs-org/karabiner-elements/blob/main/src/share/xpc_client.hpp): `src/share/xpc_client.hpp`

### Other components

- **Mac user**
- **macOS input**

## Connections

- Mac user → Settings UI: configures (evidence: `README.md`)
- Settings UI → Profiles and rules: edits
- Profiles and rules → Configuration model: defines
- Configuration monitor → Configuration model: loads (evidence: `src/share/monitor/configuration_monitor.hpp`)
- Daemon components → Configuration monitor: observes (evidence: `src/apps/CoreService/include/core_service/daemon/components_manager.hpp`)
- Settings UI → Modification assets: manages
- macOS input → Device capture: provides input
- Device capture → Event queue: queues events
- Event queue → Manipulator manager: supplies events (evidence: `src/share/manipulator/manipulator_manager.hpp`)
- Manipulator manager → Manipulator factory: uses factory (evidence: `src/share/manipulator/manipulator_manager.hpp`)
- Manipulator manager → Modifier state: updates state
- Manipulator manager → Virtual HID output: posts events
- Core service → Daemon components: starts
- Daemon components → Device capture: manages
- Console user server → Configuration monitor: observes (evidence: `src/apps/ConsoleUserServer/include/console_user_server/components_manager.hpp`)
- Console user server → Command receiver: creates (evidence: `src/apps/ConsoleUserServer/include/console_user_server/components_manager.hpp`)
- Console user server → Core service client: notifies (evidence: `src/apps/ConsoleUserServer/include/console_user_server/components_manager.hpp`)
- Core service client → XPC transport: transports requests (evidence: `src/share/core_service_daemon_client.hpp`)
- Event Viewer → Core service client: queries service
- Command-line client → Core service client: sends commands (evidence: `src/bin/cli/src/main.cpp`)
