diff --git a/osx/README.md b/osx/README.md
new file mode 100644
index 0000000..144a47f
--- /dev/null
+++ b/osx/README.md
@@ -0,0 +1,12 @@
+# OSX
+
+## Keyboard Remapping
+
+* Remap caps lock to ctrl
+    * After running the install script, open the Karabiner-Elements app, then go to preferences->Simple
+      modifications and add a new item that maps `caps_lock` to `left_control`.
+
+* Remap caps lock to esc on tap and ctrl on hold
+    * After running the install script, follow this guide starting at step 2: https://web.archive.org/web/20200513031048/https://medium.com/@pechyonkin/how-to-map-capslock-to-control-and-escape-on-mac-60523a64022b
+    * Note: I had some issues with vim sometimes losing the caps lock remap. I just went with the
+      simple caps->ctrl remap.
diff --git a/osx/capslock-to-ctrl-for-karabiner.json b/osx/capslock-to-ctrl-for-karabiner.json
new file mode 100644
index 0000000..fa5f071
--- /dev/null
+++ b/osx/capslock-to-ctrl-for-karabiner.json
@@ -0,0 +1,32 @@
+{
+    "title": "Change caps_lock to Esc and Control",
+    "rules": [
+        {
+            "description": "Post Esc if Caps is tapped, Control if held.",
+            "manipulators": [
+                {
+                    "type": "basic",
+                    "from": {
+                        "key_code": "left_control",
+                        "modifiers": {
+                            "optional": [
+                                "any"
+                            ]
+                        }
+                    },
+                    "to": [
+                        {
+                            "key_code": "left_control",
+                            "lazy": true
+                        }
+                    ],
+                    "to_if_alone": [
+                        {
+                            "key_code": "escape"
+                        }
+                    ]
+                }
+            ]
+        }
+    ]
+}
diff --git a/osx/install b/osx/install
index d9a0288..cdcd98b 100755
--- a/osx/install
+++ b/osx/install
@@ -13,6 +13,11 @@ setup_file $HOME/.dotfiles/osx/env.platform $HOME/.env.platform
 printf "\n${BOLD}Installing Git customizations...${NORMAL}\n"
 setup_file $HOME/.dotfiles/osx/gitconfig.platform $HOME/.gitconfig.platform
 
+printf "\n${BOLD}Installing key remap config...${NORMAL}\n"
+key_dest=$HOME/.config/karabiner/assets/complex_modifications/
+mkdir -p $key_dest
+setup_file $HOME/.dotfiles/osx/capslock-to-ctrl-for-karabiner.json ${key_dest}/custom-capslock.json
+
 #-----------------------------------
 # Homebrew packages
 #-----------------------------------