diff --git a/README.md b/README.md
index 2bf6c52..7bb4a4d 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,111 @@
-# shell-history-automation-tool
+# Shell History Automation Tool
 
-A CLI tool that analyzes shell command history to find patterns and suggest automation. Features fuzzy search, pattern detection, auto-alias suggestions, time-based analysis, and script export for developers.
\ No newline at end of file
+A CLI tool that analyzes shell command history to find patterns and suggest automation. It learns repetitive command sequences and offers to create aliases or scripts.
+
+## Features
+
+- **Fuzzy Search**: Search through shell history with configurable similarity thresholds
+- **Pattern Detection**: Detect repetitive command sequences and common patterns
+- **Auto-Alias Suggestions**: Automatically suggest shell aliases for detected command sequences
+- **Time-Based Analysis**: Analyze time-based patterns and suggest automation based on when commands are run
+- **Script Export**: Export detected patterns to executable shell scripts
+- **Multi-Shell Support**: Support for bash and zsh history formats
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```bash
+# Search history with fuzzy matching
+shellhist search "git status"
+
+# Detect repetitive patterns
+shellhist patterns
+
+# Get alias suggestions
+shellhist suggest-aliases
+
+# Analyze time-based patterns
+shellhist analyze-time --daily
+
+# Export patterns to script
+shellhist export-script --output ./scripts/
+```
+
+## Commands Overview
+
+### search
+Search shell history with fuzzy matching.
+
+```bash
+shellhist search "git commit" --threshold 70 --limit 10
+```
+
+### patterns
+Detect repetitive command sequences and patterns.
+
+```bash
+shellhist patterns --min-frequency 3
+```
+
+### suggest-aliases
+Generate alias suggestions for detected patterns.
+
+```bash
+shellhist suggest-aliases --auto-create
+```
+
+### analyze-time
+Analyze time-based patterns in command history.
+
+```bash
+shellhist analyze-time --daily --time-range 7d
+```
+
+### export-script
+Export detected patterns to executable shell scripts.
+
+```bash
+shellhist export-script --output ./scripts/ --name myscript
+```
+
+## Configuration
+
+The tool uses the following environment variables:
+
+- `HISTFILE`: Path to shell history file (default: ~/.bash_history or ~/.zsh_history)
+- `HISTSIZE`: Number of history entries to load
+- `SHELL`: Detects bash vs zsh for format parsing
+
+## Examples
+
+### Find similar commands you run frequently
+
+```bash
+$ shellhist search "deploy"
+Found 5 similar commands:
+  1. npm run deploy (85% match)
+  2. ./deploy.sh production (78% match)
+  3. git push origin main (72% match)
+```
+
+### Detect and create an alias for a common sequence
+
+```bash
+$ shellhist suggest-aliases
+Detected pattern: git add . && git commit -m "update" && git push
+Suggested alias: gup='git add . && git commit -m "update" && git push'
+Create this alias? [Y/n]
+```
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first.
+
+## License
+
+MIT