diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3dd58ee
--- /dev/null
+++ b/README.md
@@ -0,0 +1,42 @@
+# ferret
+
+Search DuckDuckGo in your terminal.
+
+Run `ferret` and enter a search query:
+
+![dialog box for entering search query](docs/search_input.png)
+
+Ferret will display the first page of results:
+
+![list of results scraped from DuckDuckGo](docs/results_list.png)
+
+Press Enter on a result and it will open the result in a terminal text-based web
+browser (w3m):
+
+![viewing a search result in the w3m terminal web browser](docs/w3m.png)
+
+## Why DuckDuckGo
+
+Not only does it respect your privacy, but they are also pretty lenient about
+not blocking scrapers. Google will eventually detect scrapers and force you to
+fill out a captcha.
+
+## Bugs
+
+There's [an issue]() with launching a sub program in [Cursive](), the Rust terminal
+UI library I'm using, where keyboard input doesn't quite go through and the
+cursor does not show up.
+
+## Todo
+
+* Allow pressing 0-9 take you to that Nth result (0 == 10)
+* Allow configuring colors
+* Allow configuring web browser
+* Error if screen is too small
+* Display DuckDuckGo instant answers
+* Support other search engines
+* Add search history (press up arrow to get previous search entered)
+* Cache search results
+* Add autocompletion
+* Refactor out scraping code into a separate module from the UI code
+* Add tests
diff --git a/doc/results_list.png b/doc/results_list.png
new file mode 100644
index 0000000..857067f
Binary files /dev/null and b/doc/results_list.png differ
diff --git a/doc/search_input.png b/doc/search_input.png
new file mode 100644
index 0000000..a4a85db
Binary files /dev/null and b/doc/search_input.png differ
diff --git a/doc/w3m.png b/doc/w3m.png
new file mode 100644
index 0000000..3ce8f93
Binary files /dev/null and b/doc/w3m.png differ