diff --git a/.devcontainer/README.md b/.devcontainer/README.md
index 41bcbdb8..edb741b0 100644
--- a/.devcontainer/README.md
+++ b/.devcontainer/README.md
@@ -1,3 +1,19 @@
 # devcontainer
 
-todo
+## example usage
+
+Below are some example use cases you might want to run from within the devcontainer (either within VSCode or GitHub Codespaces).
+
+### Run pre-commit
+
+```bash
+# run pre-commit
+pre-commit run --all-files
+```
+
+### Docker compose
+
+```bash
+# build the image
+docker compose up --build
+```