diff --git a/README.md b/README.md
index 174be0b..75457e2 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,27 @@
-# git-diff-explainer-cli
+# Git Diff Explainer CLI
 
-A CLI tool that uses LLMs to explain git diffs in natural language.
+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
 
-- Explain git diffs using AI (OpenAI, Anthropic, or local LLMs)
-- Support for multiple diff formats (unified, side-by-side, stats)
-- Configurable explanation depth (brief, detailed, comprehensive)
-- Interactive mode for follow-up questions
-- Batch processing of multiple files
+- **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
+# Using pip
 pip install git-diff-explainer-cli
+
+# From source
+git clone <repository>
+cd git-diff-explainer-cli
+pip install -e .
 ```
 
 ## Usage
@@ -21,29 +29,136 @@ pip install git-diff-explainer-cli
 ### Basic Usage
 
 ```bash
-gdiffer explain
+# Explain a diff from stdin
+git diff | gdiffer explain --stdin
+
+# Explain a diff file
+gdiffer explain --file changes.diff
+
+# Pass diff as argument
+gdiffer explain "diff --git a/file.py b/file.py..."
+
+# Get just the summary
+gdiffer summarize --file changes.diff
+
+# Check for issues only
+gdiffer issues --file changes.diff
 ```
 
 ### Options
 
 ```bash
---format TEXT    Output format (text, json, markdown) [default: text]
---depth TEXT     Explanation depth (brief, detailed, comprehensive) [default: detailed]
---model TEXT     LLM model to use (gpt-4, claude-3-opus, etc.)
---interactive    Enable interactive mode
---batch          Batch process multiple files
+# Output format: terminal (default), json, plain
+gdiffer explain --output json
+
+# Verbose output
+gdiffer explain --verbose
 ```
 
+## Examples
+
+### Simple Diff Explanation
+
+```bash
+$ git diff | gdiffer explain
+=== Git Diff Analysis Summary ===
+Total files changed: 1
+Files added: 0
+Files deleted: 0
+Files modified: 1
+Total changes: 3
+
+Languages:
+  - python: 1 files
+
+=== File Changes ===
+
+1. src/main.py
+   Status: modify
+   Changes: 3 lines
+   Hunk 1:
+    +import os
+    +import sys
+    def main():
+        print("Hello, World!")
+```
+
+### JSON Output
+
+```bash
+$ gdiffer explain --output json "diff --git a/test.py..."
+{
+  "summary": {
+    "total_files": 1,
+    "files_added": 0,
+    "files_deleted": 0,
+    "files_modified": 1,
+    "total_changes": 2
+  },
+  "files": [...]
+}
+```
+
+### Issue Detection
+
+```bash
+$ gdiffer issues --file sql_injection.diff
+[CRITICAL] Potential SQL Injection
+  File: db.py:5
+  Description: String concatenation or interpolation used in SQL query
+  Suggestion: Use parameterized queries or ORM methods
+```
+
+## Supported Languages
+
+- Python
+- JavaScript / TypeScript
+- Java
+- Go
+- Rust
+- C / C++
+- Ruby
+- PHP
+- And more...
+
 ## Configuration
 
-Set your API key:
+Environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `GDIFF_OUTPUT` | Output format: terminal, json, plain | terminal |
+| `GDIFF_VERBOSE` | Enable verbose output | false |
+
+## Development
 
 ```bash
-export OPENAI_API_KEY="your-key"
-# or
-export ANTHROPIC_API_KEY="your-key"
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ --cov=src/gdiffer
+
+# Type checking
+mypy src/gdiffer/
+
+# Linting
+ruff check src/gdiffer/
 ```
 
+## Error Handling
+
+Common errors and solutions:
+
+| Error | Solution |
+|-------|----------|
+| Invalid git diff format | Provide a valid unified diff format |
+| No changes detected | Ensure the diff contains actual code changes |
+| Unsupported language | Use a supported language or file extension |
+
 ## License
 
 MIT