MCPInstall

karabiner

Configure Karabiner-Elements keyboard remapping using Goku EDN syntax. Use when creating keybindings, layers, simlayers, app-specific shortcuts, or modifying karabiner.edn.

Installs
53
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/johnlindquist/claude --skill karabiner
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads karabiner automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Karabiner (via Goku)

Configure macOS keyboard remapping with GokuRakuJoudo - an EDN-based DSL that compiles to Karabiner-Elements JSON.

Why Goku?

Karabiner's native JSON is verbose (20,000+ lines). Goku's EDN format is 10-50x more concise:

;; Goku: 1 line
[:caps_lock :escape]

;; Karabiner JSON: ~30 lines

Prerequisites

# Install Goku
brew install yqrashawn/goku/goku

# Start as service (watches ~/.config/karabiner.edn)
brew services start goku

# Or run once manually
goku

Config location: ~/.config/karabiner.edn

Logs: ~/Library/Logs/goku.log

EDN Syntax Quick Reference

Basic Structure

{:main [{:des "Rule description"
         :rules [[:from :to]
                 [:from2 :to2]]}]}

Keycodes

All keys use keyword syntax: :a, :1, :f19, :spacebar, :return_or_enter

Find keycodes:

Modifier Syntax

SymbolModifierExample
!CLeft Command:!Ca = Cmd+A
!TLeft Control:!Ta = Ctrl+A
!OLeft Option:!Oa = Opt+A
!SLeft Shift:!Sa = Shift+A
!QRight Command:!Qa
!WRight Control:!Wa
!ERight Option:!Ea
!RRight Shift:!Ra
!FFn:!Fa
!PCaps Lock:!Pa
!!Hyper (Cmd+Ctrl+Opt+Shift):!!a
##Optional any modifier:##a

Combine modifiers: :!CTSa = Cmd+Ctrl+Shift+A

Rule Format

[:from :to]                           ;; Basic
[:from :to :condition]                ;; With condition
[:from :to :condition {:alone :x}]    ;; With options

Multiple Keys

;; Press sequence
[:a [:1 :2 :3]]           ;; a -> types 1, 2, 3

;; Simultaneous press (from)
[[:j :k] :escape]         ;; j+k together -> escape

Shell Commands

[:!!1 "open -a Safari"]   ;; Hyper+1 runs shell command

Conditions

Application Conditions

{:applications {:chrome ["^com\\.google\\.Chrome$"]
                :code   ["com.microsoft.VSCode"]}
 :main [{:des "Chrome only"
         :rules [[:a :b :chrome]]}]}

Device Conditions

{:devices {:hhkb [{:vendor_id 1278 :product_id 51966}]}
 :main [{:rules [[:a :b :hhkb]]}]}

Input Source Conditions

{:input-sources {:us {:input_source_id "com.apple.keylayout.US"}}
 :main [{:rules [[:a :b :us]]}]}

Combining & Negating Conditions

[:a :b [:chrome :hhkb]]    ;; Both conditions
[:a :b [:!chrome]]         ;; NOT in Chrome

Layers

Simlayers (Recommended)

Fast, simultaneous-key based layers - best for typing speed:

{:simlayers {:w-mode {:key :w}}        ;; Hold W activates layer
 :main [{:des "w-mode shortcuts"
         :rules [:w-mode                ;; Apply to this layer
                 [:e "open -a Finder"]  ;; W+E opens Finder
                 [:r "open -a Safari"]  ;; W+R opens Safari
                 ]}]}

Simlayer options:

{:simlayers {:w-mode {:key :w
                      :modi {:mandatory [:left_control]}}}}  ;; Ctrl+W activates

Standard Layers (Tap/Hold)

Different behavior on tap vs hold:

{:layers {:caps-mode {:key :caps_lock
                      :alone {:key :escape}}}}  ;; Tap=Esc, Hold=layer

Manual Layer Variables

;; Set variable on keydown, clear on keyup
[:w ["w-mode" 1] nil {:afterup ["w-mode" 0] :alone :w}]

;; Use the variable as condition
[:e :!Ce ["w-mode" 1]]  ;; W+E -> Cmd+E (only when w-mode=1)

Templates

Reusable shell command patterns:

{:templates {:open "open -a '%s'"
             :launch "/path/to/script.sh %s"
             :alfred "osascript -e 'tell application \"Alfred\" to run trigger \"%s\"'"}
 :main [{:rules [[:!!1 [:open "Safari"]]      ;; %s replaced with Safari
                 [:!!2 [:launch "arg1"]]]}]}

Predefined Aliases

:froms (Input Keys)

{:froms {:delete {:key :delete_or_backspace}
         :return {:key :return_or_enter}
         :mouse1 {:pkey :button1}}}

:tos (Output Actions)

{:tos {:spotlight {:key :spacebar :modi :command}
       :paste {:key :v :modi :command}
       :shift-click {:pkey :button1 :modi :left_shift}}}

Custom Modifier Sets

{:modifiers {:hyper [:command :shift :control :option]
             :meh   [:shift :control :option]}}

Advanced Options

Fourth position in rules:

[:from :to :condition {
  :alone :key              ;; to_if_alone
  :held :key               ;; to_if_held_down
  :afterup :key            ;; to_after_key_up
  :delayed {:invoked :x :canceled :y}
  :params {:alone_timeout 200}
}]

Profile Settings

{:profiles {:Default {:default true
                      :sim 250        ;; Simultaneous threshold (ms)
                      :delay 500      ;; Delayed action time (ms)
                      :alone 1000     ;; to_if_alone timeout (ms)
                      :held 500}}}    ;; Held threshold (ms)

Common Workflows

Add a Simple Remap

{:main [{:des "Caps to Escape"
         :rules [[:caps_lock :escape]]}]}

Add App-Specific Shortcut

{:applications {:chrome ["com.google.Chrome"]}
 :main [{:des "Chrome shortcuts"
         :rules [[:!Cl :!Ct :chrome]]}]}  ;; Cmd+L -> Cmd+T in Chrome

Create a Layer

{:simlayers {:nav {:key :spacebar}}
 :main [{:des "Navigation layer"
         :rules [:nav
                 [:h :left_arrow]
                 [:j :down_arrow]
                 [:k :up_arrow]
                 [:l :right_arrow]]}]}

Hyper Key Setup

{:main [{:des "Caps Lock to Hyper"
         :rules [[:caps_lock :!CTOSleft_shift nil {:alone :escape}]]}]}

CLI Commands

goku           # Compile karabiner.edn once
gokuw          # Watch mode (compile on change)
goku -h        # Help

# Service management
brew services start goku    # Start watch service
brew services stop goku     # Stop service
brew services restart goku  # Restart after changes

# Check logs
tail -f ~/Library/Logs/goku.log

Validation & Debugging

  1. Check syntax: Goku reports EDN parse errors
  2. View output: ~/.config/karabiner/karabiner.json
  3. Use EventViewer: Karabiner-EventViewer.app shows key events
  4. Check logs: tail ~/Library/Logs/goku.log

Best Practices

  1. Use simlayers for frequently-accessed shortcuts (faster than hold-layers)
  2. Group rules by purpose with descriptive :des tags
  3. Use templates for repeated shell command patterns
  4. Define aliases in :froms/:tos for complex key definitions
  5. Test incrementally - add one rule, verify, repeat
  6. Back up your config before major changes

Resources

FAQ

What does the karabiner skill do?

Configure Karabiner-Elements keyboard remapping using Goku EDN syntax. Use when creating keybindings, layers, simlayers, app-specific shortcuts, or modifying karabiner.edn.

How do I install karabiner?

Run npx skills add https://github.com/johnlindquist/claude --skill karabiner in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/karabiner/ (personal) or .claude/skills/karabiner/ (project).

Which AI agents can use karabiner?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is karabiner safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains karabiner?

It is published by johnlindquist in johnlindquist/claude. It has 53 recorded installs.

More from johnlindquist/claude

View all →

gemini-image

johnlindquist/claude

Analyze images using Gemini's vision capabilities. Use for image analysis, text extraction from screenshots, and visual content understanding.

Media & Creative1.2K installs

memory

johnlindquist/claude

Persistent knowledge storage using basic-memory CLI. Use to save notes, search memories semantically, and build context for topics across sessions.

Docs & Writing362 installs

raycast-extension

johnlindquist/claude

Open the skill to read its SKILL.md instructions.

321 installs

brainstorm

johnlindquist/claude

Generate ideas and explore possibilities with AI. Use for creative problem solving, generating alternatives, and expanding on concepts.

deepwiki

johnlindquist/claude

Query DeepWiki for repository documentation and structure. Use to understand open source projects, find API docs, and explore codebases.

Docs & Writing269 installs

think

johnlindquist/claude

Open the skill to read its SKILL.md instructions.

258 installs

Popular other skills

View category →

hyperframes-cli

heygen-com/hyperframes

The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.

1.3M installs

triage

mattpocock/skills

Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.

1M installs

ask-matt

mattpocock/skills

Ask which skill or flow fits your situation. A router over the skills in this repo.

778.4K installs

to-questionnaire

mattpocock/skills

Turn a decision you can't fully answer into a questionnaire for someone else to fill in.

508.9K installs

wait-what

mattpocock/skills

Stop. That last message did not land: re-pitch it.

459.7K installs

loop-me

mattpocock/skills

Grill me about specs for the workflows I want to build, within this workspace.

447.9K installs