diff --git a/.gitignore b/.gitignore
index 6fd0a37..1c1a0e6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -39,3 +39,4 @@ luac.out
 *.x86_64
 *.hex
 
+*~
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..021eb7b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,46 @@
+# A simple CAPS LOCK widget for Awesome
+
+Useful when you have a keyboard that does not have a CAPS LOCK indicator.
+
+This widget is really simple and parses the output of `xset` to figure out
+whether CAPS LOCK is active or not. (Hint: you need the `xset` utility for this
+widget to work)
+
+# Installation
+
+1. Ensure that `xset` is available to you on your system.
+2. Copy `capslock.lua` in your `~/.config/awesome/rc.lua` (e.g. by cloning this
+repository).
+3. Restart Awesome (e.g. press `modkey + Control` or run `awesome-client
+   "awesome.restart()"` from a terminal).
+
+# Usage
+
+For **Awesome 4.x**, add the following to your `~/.config/awesome/rc.lua`:
+
+``` lua
+local capslock = require("capslock")
+
+-- more config here
+
+    -- Add widgets to the wibox
+    s.mywibox:setup {
+-- more config here
+      { -- Right widgets
+        layout = wibox.layout.fixed.horizontal,
+        wibox.widget.systray(),
+        capslock,
+-- more config here
+-- {{{ Key bindings
+local globalkeys = awful.util.table.join(
+  capslock.key,
+-- more config follows
+```
+
+Now, when you activate CAPS LOCK, a chevron sign will be
+displayed: ![capslock screenshot](/screenshots/capslock_widget.png?raw=true)
+
+# Contributing
+
+If you have ideas about how to make this better, feel free to open an issue or
+submit a pull request.
diff --git a/capslock.lua b/capslock.lua
new file mode 100644
index 0000000..296ae63
--- /dev/null
+++ b/capslock.lua
@@ -0,0 +1,82 @@
+--[[
+
+  Copyright 2017 Stefano Mazzucco <stefano AT curso DOT re>
+
+  This program is free software: you can redistribute it and/or modify it under
+  the terms of the GNU General Public License as published by the Free Software
+  Foundation, either version 3 of the License, or (at your option) any later
+  version.
+
+  This program is distributed in the hope that it will be useful, but WITHOUT
+  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+  details.
+
+  You should have received a copy of the GNU General Public License along with
+  this program.  If not, see <https://www.gnu.org/licenses/gpl-3.0.html>.
+
+]]
+
+--[[
+  A simple widget to show whether Caps Lock is active.
+  Requirements:
+  - Awesome 4.x
+  - xset
+
+  @usage
+  capslock = require("capslock")
+  -- Add widget to wibox
+  s.mywibox:setup {
+  layout = wibox.layout.align.horizontal,
+  { -- Left widgets
+    layout = wibox.layout.fixed.horizontal,
+    capslock
+  }
+  -- more stuff
+  }
+  -- Add key to globalkeys
+  globalkeys = awful.util.table.join(globalkeys, capslock.key)
+
+]]
+
+local math = math
+local awful = require("awful")
+local gears = require("gears")
+local wibox = require("wibox")
+
+local checkbox = wibox.widget {
+  checked = false,
+  border_width = 0,
+  paddings = 2,
+  check_shape = function (cr, w, h)
+    gears.shape.transform(gears.shape.powerline)
+      :rotate(-math.pi/2)
+      :translate(-h, 0)(cr, w, h)
+  end,
+  widget = wibox.widget.checkbox
+}
+
+local function check_caps_lock()
+  awful.spawn.with_line_callback(
+    "bash -c 'sleep 0.2 && xset q'",
+    {
+      stdout = function (line)
+        if line:match("Caps Lock") then
+          local status = line:gsub(".*(Caps Lock:%s+)(%a+).*", "%2")
+          if status == "on" then
+            checkbox.checked = true
+          else
+            checkbox.checked = false
+          end
+        end
+      end
+    }
+  )
+end
+
+local capslock = awful.key({}, "Caps_Lock", check_caps_lock)
+checkbox.key = capslock
+
+check_caps_lock()
+
+return checkbox
diff --git a/screenshots/capslock_widget.png b/screenshots/capslock_widget.png
new file mode 100644
index 0000000..c272f36
Binary files /dev/null and b/screenshots/capslock_widget.png differ