diff --git a/README.md b/README.md
index 255538d..1ea36d0 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,62 @@
-# git-diff-explainer-cli
+# Git Diff Explainer CLI
 
-A CLI tool that parses git diffs and provides intelligent, contextual explanations of code changes. Identifies programming language, summarizes changes, flags potential issues, and suggests improvements - all running locally without external API dependencies.
\ No newline at end of file
+A CLI tool that parses git diffs and provides intelligent, contextual explanations of code changes. Identifies programming language, summarizes changes, flags potential issues, and suggests improvements - all running locally without external API dependencies.
+
+## Features
+
+- Parse git diffs/patches: Extract file names, hunks, and code changes from unified diff format
+- Identify programming language: Detect language from file extensions and code patterns
+- Summarize changes: Generate human-readable summaries of what each change does
+- Flag potential issues: Detect bugs, security vulnerabilities, and code smells
+- Suggest improvements: Provide specific refactoring suggestions
+- Local execution: Runs entirely offline using local libraries
+- Color-coded output: Terminal output with ANSI colors for better readability
+
+## Installation
+
+```bash
+pip install git-diff-explainer-cli
+```
+
+Or from source:
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/git-diff-explainer-cli.git
+cd git-diff-explainer-cli
+pip install -e .
+```
+
+## Usage
+
+### Basic Usage
+
+```bash
+git diff | gdiffer explain --stdin
+gdiffer explain --file changes.diff
+gdiffer explain "diff --git a/file.py b/file.py..."
+gdiffer summarize --file changes.diff
+gdiffer issues --file changes.diff
+```
+
+### Options
+
+```bash
+gdiffer explain --output json  # terminal (default), json, plain
+gdiffer explain --verbose
+```
+
+## Supported Languages
+
+Python, JavaScript/TypeScript, Java, Go, Rust, C/C++, Ruby, PHP, and more.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+pytest tests/ --cov=src/gdiffer
+```
+
+## License
+
+MIT