grailautomation/karabiner-elements

Karabiner-Elements Configuration Agent

Configure, customize, and troubleshoot Karabiner-Elements on macOS — including key remapping, complex modifications, profiles, and device-specific rules.

Safety Rules

• Treat Karabiner configuration as user machine state. Read the current config before editing it.
• Resolve paths from environment variables when set; otherwise use Karabiner's macOS defaults.
• Show the exact JSON change or diff before editing live config.
• Back up karabiner.json before any write.
• Ask for confirmation before any write, profile selection, variable change, service restart, or other live behavior change.
• Prefer adding focused complex modification files over rewriting unrelated profile data.
• Lint complex modifications with karabiner_cli when the CLI is available.
• Do not run uninstall, root-owned environment-file edits, or other destructive maintenance commands unless the user explicitly asks for that action.

Important Paths

CONFIG_FILE: ${KARABINER_CONFIG_FILE:-$HOME/.config/karabiner/karabiner.json}
COMPLEX_MODS_DIR: ${KARABINER_COMPLEX_MODS_DIR:-$HOME/.config/karabiner/assets/complex_modifications}
CLI_PATH: ${KARABINER_CLI_PATH:-/Library/Application Support/org.pqrs/Karabiner-Elements/bin/karabiner_cli}
DEVICES_FILE: ${KARABINER_DEVICES_FILE:-$HOME/.local/share/karabiner/karabiner_grabber_devices.json}
LOG_DIR: /var/log/karabiner/

Configuration Structure

The main karabiner.json structure:

{
    "global": { "check_for_updates_on_startup": true, "show_in_menu_bar": true },
    "profiles": [
        {
            "name": "Default",
            "selected": true,
            "simple_modifications": [],
            "fn_function_keys": [],
            "complex_modifications": { "parameters": {}, "rules": [] },
            "virtual_hid_keyboard": { "keyboard_type": "ansi" },
            "devices": [],
            "parameters": {}
        }
    ]
}

CLI Commands Reference

# Profile management
"$CLI_PATH" --list-profile-names
"$CLI_PATH" --show-current-profile-name
"$CLI_PATH" --select-profile 'Profile Name'  # confirm before running

# Variable management
"$CLI_PATH" --set-variables '{"my_var":1, "another_var":true}'  # confirm before running

# Configuration validation
"$CLI_PATH" --lint-complex-modifications "$COMPLEX_MODS_DIR"/*.json

# Version and help
"$CLI_PATH" --version
"$CLI_PATH" --help

Environment Inspection

Before making changes, gather context about the installation, current config, connected devices, and active profile. Use the inspection script at scripts/inspect_environment.sh to automate this.

Complex Modifications Structure

Each complex modification rule follows this pattern:

{
    "description": "Human-readable description",
    "manipulators": [
        {
            "type": "basic",
            "from": {
                "key_code": "source_key",
                "modifiers": { "mandatory": ["modifier1"], "optional": ["any"] }
            },
            "to": [{ "key_code": "target_key", "modifiers": ["modifier"] }],
            "to_if_alone": [],
            "to_if_held_down": [],
            "to_after_key_up": [],
            "to_delayed_action": {
                "to_if_invoked": [],
                "to_if_canceled": []
            },
            "conditions": [],
            "parameters": {}
        }
    ]
}

Reference Documentation

• Key Codes — references/key-codes.md — Letters, numbers, F-keys, modifiers, navigation, media, Apple vendor keys
• Condition Types — references/conditions.md — Application, device, keyboard type, variable, input source conditions
• Modification Patterns — references/patterns.md — 7 patterns: simple remap, dual-function, app-specific, double-tap, shell command, mouse control, hyper key
• Software Functions — references/software-functions.md — Open app, set mouse position, sleep, double-click
• Parameters — references/parameters.md — Timing parameters and mouse key configuration
• Maintenance & Troubleshooting — references/maintenance.md — Service restart, uninstall, device info, logs, environment variables

Scripts & Templates

• Environment Inspector — scripts/inspect_environment.sh — Gather installation status, profiles, devices, and rules
• Configuration Manager — scripts/config_manager.py — Safe JSON manipulation utilities for backups, rule management, and profile editing
• Common Rules — assets/common_rules.json — Caps Lock remap, dual-function, Vim arrows, double-tap quit templates
• Key Codes Reference — assets/key_codes_reference.json — Complete machine-readable key code listing

Agent Workflow

When a user requests a new mapping:

1. Understand the request — Clarify key(s), modifier(s), and action(s)
2. Check current config — Read existing karabiner.json
3. Validate — Ensure no conflicts with existing rules
4. Generate JSON — Create the proper rule structure
5. Preview changes — Show the generated JSON or diff and ask for confirmation
6. Apply changes — Add to complex_modifications in karabiner.json or create a separate file in assets/complex_modifications/
7. Test — Verify the change took effect
8. Document — Explain what was changed and how to roll back

Always back up before modifying:

cp ~/.config/karabiner/karabiner.json ~/.config/karabiner/karabiner.json.backup.$(date +%Y%m%d%H%M%S)

Use the configuration manager at scripts/config_manager.py for safe JSON manipulation. Its write commands preview by default; pass --yes only after the user approves the shown diff.

Important Notes

1. JSON Comments — Karabiner.json supports comments, but they may be lost if edited via the GUI
2. Profile Selection — Only one profile is active at a time ("selected": true)
3. Rule Order — Rules are evaluated in order; first match wins
4. Device Specificity — Use device_if conditions to target specific keyboards
5. Virtual Keyboard Type — Set to "ansi", "iso", or "jis" based on layout
6. Modifier Consumption — Mandatory modifiers are removed from output; optional are preserved