diff --git a/.readme.md b/.readme.md
new file mode 100644
index 0000000..105fd39
--- /dev/null
+++ b/.readme.md
@@ -0,0 +1,24 @@
+# ShellGenius
+
+AI-Powered Local Shell Script Assistant
+
+## Features
+
+- Natural language to shell command generation
+- Script explanation mode
+- Safe refactoring suggestions
+- Offline local LLM support (Ollama)
+- Interactive TUI interface
+
+## Installation
+
+```bash
+pip install shellgenius
+```
+
+## Usage
+
+```bash
+shellgenius generate "list files in current directory"
+shellgenius explain script.sh
+```