diff --git a/README.md b/README.md
index 88e27b4..e11a40f 100644
--- a/README.md
+++ b/README.md
@@ -1,101 +1,255 @@
-# gitclean
+
-A fast Rust CLI to scan and clean files and directories ignored by .gitignore across your project. It detects ignored items, shows sizes, and lets you interactively delete them.
+# ๐งน gitclean
-## Features
+### _Clean your Git projects like a pro_
-- Recursively collects .gitignore rules (supports nested .gitignore)
-- Extra ignore patterns via CLI (`-i ".env*,.config*"`)
-- Preserves common secret/config files by default (negated patterns)
-- Parallel size computation (WalkDir + Rayon)
-- TUI multiselect (inquire) with sizes, sorted descending
-- Informative spinners and logs (indicatif + console)
+**A blazingly fast Rust CLI that scans and removes files ignored by `.gitignore` โ interactively and safely.**
-## Install
+[](https://crates.io/crates/gitclean)
+[](https://opensource.org/licenses/MIT)
+[](https://www.rust-lang.org/)
-Build from source:
+[Installation](#-installation) โข
+[Features](#-features) โข
+[Usage](#-usage) โข
+[Examples](#-examples) โข
+[Library](#-library-usage)
+
+
+
+---
+
+## ๐ฏ Why gitclean?
+
+Ever wondered how much disk space those `node_modules`, `target`, or `.next` folders are eating up across your projects? **gitclean** gives you **instant visibility** and **safe cleanup** of all ignored files and directories.
+
+### โจ What makes it special?
+
+- **โก Blazingly Fast** โ Written in Rust with parallel processing
+- **๐ฏ Smart Detection** โ Recursively respects all nested `.gitignore` files
+- **๐ Safe by Default** โ Preserves secrets like `.env` files automatically
+- **๐ Visual Insights** โ See sizes before you delete
+- **๐จ Beautiful TUI** โ Interactive multiselect with sorted results
+- **๐ก๏ธ Zero Risk** โ Review and confirm before any deletion
+
+---
+
+## ๐ Installation
+
+Install directly from crates.io:
```bash
-cargo install --path .
+cargo install gitclean
```
-Or build a release binary:
+That's it! Now you can use `gitclean` anywhere.
+
+---
+
+## โจ Features
+
+| Feature | Description |
+|---------|-------------|
+| ๐ **Recursive Scanning** | Collects rules from all `.gitignore` files in your project tree |
+| ๐ฏ **Custom Patterns** | Add extra ignore patterns via CLI (`-i ".env*,.config*"`) |
+| ๐ **Smart Preservation** | Automatically protects common secret/config files |
+| โก **Parallel Processing** | Lightning-fast size computation with WalkDir + Rayon |
+| ๐จ **Interactive TUI** | Beautiful multiselect interface with sizes, sorted descending |
+| ๐ **Detailed Logging** | Informative spinners and progress indicators |
+
+---
+
+## ๐ Usage
```bash
-cargo build --release
-./target/release/gitclean .
+gitclean [OPTIONS]
```
-## Usage
+### Options
-```bash
-gitclean [--ignores|-i "pattern1,pattern2,..."]
```
+ Project root directory to scan
+-i, --ignores Extra ignore patterns (comma-separated)
+-h, --help Print help information
+-V, --version Print version information
+```
+
+---
+
+## ๐ก Examples
-Examples:
+### Clean current directory
```bash
-# Current directory
gitclean .
+```
+
+**Output:**
+```
+๐งน gitclean v1.0.0
+๐ Root: /home/user/projects/my-app
+๐ Default patterns: 15
+๐ฏ Extra patterns: 0
+
+โ Loading .gitignore files...
+โ Found 3 .gitignore files
+
+โ Scanning ignored items...
+โ Found 127 ignored items (45 dirs, 82 files)
+
+โ Computing sizes...
+โ Sizes computed
+
+โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+โ Select items to delete (Space to toggle) โ
+โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+
+ [ ] node_modules/ 1.2 GB
+ [ ] target/ 856 MB
+ [ ] .next/ 234 MB
+ [ ] dist/ 89 MB
+ [ ] coverage/ 12 MB
+```
+
+### Scan specific project
+
+```bash
+gitclean ~/projects/my-app
+```
-# Custom root path
-gitclean /path/to/project
+### Add custom ignore patterns
-# Add extra ignore patterns (comma-separated)
+```bash
gitclean . -i ".env*,.config*,*.log"
```
-## Logs & UX
+This will additionally ignore:
+- All files starting with `.env`
+- All files starting with `.config`
+- All `.log` files
+
+---
-- Startup header: shows version, root, default and extra pattern counts
-- Spinners for: loading .gitignore, scanning ignored items, computing sizes
-- Summary after scanning: total ignored (dirs/files)
-- Deletion logs include size per item
+## ๐จ Interactive Experience
-## Library usage
+gitclean provides a delightful CLI experience:
-Core logic is exposed as a library for reuse:
+1. **๐ Spinner animations** while scanning
+2. **๐ Progress indicators** for long operations
+3. **๐ Organized results** sorted by size (largest first)
+4. **โ
Multi-select interface** to choose what to delete
+5. **โ Confirmation logs** showing freed space
+
+---
+
+## ๐ Library Usage
+
+Use `gitclean` as a library in your own Rust projects:
```rust
-use gitclean::{gather_gitignores, scan_ignored_files, calculate_sizes, format_size};
+use gitclean::{
+ gather_gitignores,
+ scan_ignored_files,
+ calculate_sizes,
+ format_size
+};
use indicatif::ProgressBar;
use std::path::Path;
-let root = Path::new(".").canonicalize().unwrap();
-let spinner = ProgressBar::hidden();
-let extra: Vec = vec![];
-let map = gather_gitignores(&root, &spinner, &extra)?;
-let ignored = scan_ignored_files(&root, &map, &spinner)?;
-let items = calculate_sizes(ignored, &spinner, &root)?;
-println!("{} items", items.len());
+fn main() -> anyhow::Result<()> {
+ let root = Path::new(".").canonicalize()?;
+ let spinner = ProgressBar::hidden();
+ let extra: Vec = vec![];
+
+ // Gather all .gitignore rules
+ let map = gather_gitignores(&root, &spinner, &extra)?;
+
+ // Scan for ignored files
+ let ignored = scan_ignored_files(&root, &map, &spinner)?;
+
+ // Calculate sizes
+ let items = calculate_sizes(ignored, &spinner, &root)?;
+
+ println!("Found {} ignored items", items.len());
+ for item in items {
+ println!("{}: {}", item.path.display(), format_size(item.size));
+ }
+
+ Ok(())
+}
+```
+
+---
+
+## ๐๏ธ Architecture
+
+gitclean is built with a clean modular structure:
+
```
+src/
+โโโ lib.rs โ Public API exports
+โโโ patterns.rs โ Default ignore patterns
+โโโ types.rs โ Core types (ItemWithSize)
+โโโ ignore.rs โ .gitignore parsing
+โโโ scan.rs โ Scanning logic
+โโโ size.rs โ Size computation
+โโโ fsops.rs โ File operations
+โโโ util.rs โ Utilities (format_size)
+โโโ main.rs โ CLI interface
+```
+
+Each module is designed to be **reusable** and **testable**.
-## Module layout
+---
-- `src/lib.rs`: public re-exports
-- `src/patterns.rs`: default ignore patterns
-- `src/types.rs`: shared types (`ItemWithSize`)
-- `src/ignore.rs`: .gitignore loading (`gather_gitignores`)
-- `src/scan.rs`: scan logic (`scan_ignored_files`, `is_path_ignored`)
-- `src/size.rs`: size computation (`calculate_sizes`)
-- `src/fsops.rs`: file ops (`remove_item`)
-- `src/util.rs`: helpers (`format_size`)
-- `src/main.rs`: thin CLI using the library
+## ๐ ๏ธ Development
-## Development
+### Run tests
```bash
-# Run tests
cargo test
+```
+
+### Build release
-# Build release
+```bash
cargo build --release
+./target/release/gitclean .
+```
+
+### Run locally
+
+```bash
+cargo run -- .
```
-## Contributing
+---
+
+## ๐ค Contributing
+
+Contributions are welcome! Here's how you can help:
+
+1. ๐ด Fork the repository
+2. ๐ฟ Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. ๐พ Commit your changes (`git commit -m 'Add amazing feature'`)
+4. ๐ค Push to the branch (`git push origin feature/amazing-feature`)
+5. ๐ Open a Pull Request
+
+Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) and follow the [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).
+
+---
+
+## ๐ License
+
+MIT ยฉ 2025 [Jordy Fontoura](https://github.com/jordyfontoura)
+
+---
+
+
-Contributions are welcome! Please read `CONTRIBUTING.md` and follow the `CODE_OF_CONDUCT.md`.
+**Made with โค๏ธ and ๐ฆ Rust**
-## License
+[โฌ Back to top](#-gitclean)
-MIT ยฉ 2025 Jordy Fontoura
+