diff --git a/README.md b/README.md
new file mode 100644
index 0000000..aa827d3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,37 @@
+# minishell
+
+the result of a group project at 42 school, made by me and [Joris Schaft](https://github.com/BgNounours).
+
+it's a very basic shell like sh or bash. it is not POSIX.
+
+it supports:
+- `>`, `<`, `>>`, `<<` redirections
+- `|` pipes
+- environment variables and $?
+- some built-in commands
+
+## compile and run
+
+this project is for linux (it may also work on macOS i have no idea).
+
+1. in your terminal, run `make -v`.
+if you have a `command not found` error or equivalent, you will need to install `make`. on ubuntu / debian, run:
+```sh
+$ sudo apt install make
+```
+
+2. clone the repository and cd inside it:
+```sh
+$ git clone https://gitea.zaclys.com/frzysk/42_minishell
+$ cd 42_minishell
+```
+
+3. build:
+```sh
+$ make
+```
+
+4. run:
+```
+$ ./minishell
+```