diff --git a/README.md b/README.md
new file mode 100644
index 0000000..37d56a7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,82 @@
+# Tampy
+
+A Python compiler/transpiler that converts Tamil code syntax to Python.
+
+## Features
+
+- **Build mode**: Generate Python code from Tamil syntax
+- **Run mode**: Build and execute Tamil code directly
+- **Configurable keywords**: Custom keyword mappings via JSON
+- **Minimal dependencies**: Uses Python's built-in `ast` module
+
+## Installation
+
+```bash
+pip install tampy
+```
+
+## Usage
+
+### Build (generate Python code)
+
+```bash
+tampy build my_script.tampy
+# Generates: my_script.py
+```
+
+### Run (build and execute)
+
+```bash
+tampy run my_script.tampy
+```
+
+## Example
+
+**Input (Tamil code):**
+```python
+x = 1
+y = 2
+if x > y:
+    print("x is greater")
+else:
+    print("y is greater")
+```
+
+**Output:**
+```python
+x = 1
+y = 2
+if x > y:
+    print('x is greater')
+else:
+    print('y is greater')
+```
+
+## Configuration
+
+Edit `src/tampy/keywords.json` to customize keyword mappings:
+
+```json
+{
+  "print": "இருப்பு",
+  "if": "இணை",
+  "for": "ஒவ்வொரு"
+}
+```
+
+## Development
+
+```bash
+# Run tests
+pytest tests/
+
+# Install in development mode
+pip install -e ".[dev]"
+
+# Run tests with coverage
+pytest --cov=src
+```
+
+## License
+
+MIT