diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..8193ce3
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,21 @@
+
+## filter mod
+
+This mod adds a simple chat filter. There is no default word list,
+and adding words to the filter list is done through the `/filter`
+chat command. You need the `server` priv to use the chat command.
+
+The `/filter` chat command can `add`, `remove` or `list` words. The
+words are stored in `mod_storage`, which means that this mod requires
+0.4.16 or above to function.
+
+If a player speaks a word that is listed in the filter list, they are
+muted for 1 minute. After that, their `shout` privilege is restored.
+If they leave, their `shout` privilege is still restored, but only after
+the time expires, not before.
+
+## Bugs
+
+- the `shout` priv is permanently lost if the server shuts down while
+a player is muted.
+