diff --git a/README.md b/README.md
new file mode 100644
index 0000000..05946c5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,15 @@
+# xkb hypermode configuration
+
+These are my personal bindings for xkb. They are quite hacky and likely won't be useful to anyone else as-is. Note this layout is only useful in combination with xcape (otherwise some very important keys would be missing).
+
+A summary of the modification:
+- based on English-US layout
+- R-Ctrl = Caps Lock
+- L-Ctrl = L-Hyper
+- L-Super = embedded numpad modifier (with the 4 of the numpad on the j key)
+- Space = R-Alt
+- R-Alt = R-Hyper
+- Caps Lock = L-Ctrl
+- Return = R-Ctrl
+- Tab = L-Super
+- Backslash = R-Super