diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ef438e8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,20 @@
+# tagtotoot
+
+This terrible script scrapes configured mastodon instances for configured tags
+and feeds the resulting list of toot URLs to your (single-user?) instances
+search API to fetch them for the federated timelime (or hashtag search, if your
+instances software supports that and why would it?)
+
+If you want to use this copy `config.example.yaml` to `config.yaml` and fill
+in the blanks. You can get a bearer token by using pinafore, logging into
+your instance, open the network console (F12 in firefox), search for something
+and check the request headers on the GET operation.
+
+All search requests made by this script are slow and blocking.
+If you schedule this to run at periodic intervals be sure to have some sort of
+locking so the script is not executed while the previous run is still working.
+
+## Requirements
+
+* Python
+* python-requests library