docs: update documentation for usage metrics

- Update README with metrics feature details
- Add metrics section to command usage documentation
- Update CHANGELOG with new features
- Create detailed usage metrics documentation

📝 Enhance documentation to explain the new metrics functionality

Author: Arakiss

CHANGELOG.md

@@ -1,7 +1,12 @@
 # Changelog
 
-## [1.0.1] - 2024-12-10
+## [Unreleased]
+### ✨ Features
+- ✨ feat: add local metrics and usage statistics
+- 🔧 fix: update console print methods in stats command
+- 🐛 fix: continue staging files when a file is not found or deleted
 
+## [1.0.1] - 2024-12-10
 
 ### 📦 Build System
 - bump version to 1.0.1

README.md

@@ -61,6 +61,7 @@ loom -y  # Non-interactive mode
 - 🧵 **Smart Batching**: Weaves multiple changes into coherent, logical commits
 - 📊 **Complexity Analysis**: Identifies when commits are getting too large or complex
 - 💰 **Cost Control**: Built-in token and cost estimation to keep API usage efficient
+- 📈 **Usage Metrics**: Track your usage, cost savings, and productivity gains with built-in metrics
 - 🔍 **Binary Support**: Special handling for binary files with size and type detection
 - 🎨 **Beautiful CLI**: Rich, colorful interface with clear insights and warnings
 
@@ -85,16 +86,38 @@ CommitLoom can be invoked using either of these commands:
 
 ```bash
 # Using the full name
-loom [options]
+loom [command] [options]
 
 # Using the short alias
-cl [options]
+cl [command] [options]
 ```
 
-Both commands support the same options:
+#### Available Commands
+
+- `loom commit` (or simply `loom`): Generate a commit message and commit your changes
+- `loom stats`: Display detailed usage statistics and metrics
+
+#### Options
+
 - `-y, --yes`: Auto-confirm all prompts (non-interactive mode)
 - `-c, --combine`: Combine all changes into a single commit
-- `-v, --verbose`: Enable verbose logging
+- `-d, --debug`: Enable debug logging
+
+#### Usage Examples
+
+```bash
+# Basic usage (interactive mode)
+loom
+
+# Non-interactive mode with combined commits
+loom -y -c
+
+# View usage statistics
+loom stats
+
+# View debug information with statistics
+loom stats -d
+```
 
 ### API Key Configuration
 
@@ -196,6 +219,25 @@ Yes! Use the `-y` flag for non-interactive mode:
 loom -y
 ```
 
+### How does CommitLoom track metrics and usage statistics?
+
+CommitLoom keeps track of various metrics to help you understand your usage patterns:
+
+- **Usage tracking**: Number of commits generated, tokens used, and associated costs
+- **Time savings**: Estimated time saved compared to writing commit messages manually
+- **Repository statistics**: Which repositories you use CommitLoom with most frequently
+- **Model usage**: Performance metrics for different AI models
+- **Cost analysis**: Detailed breakdown of token usage and associated costs
+
+All metrics are stored locally in your user data directory (`~/.local/share/commitloom/metrics` on Linux) and are never sent to external servers.
+
+To view your metrics, simply run:
+```bash
+loom stats
+```
+
+For detailed documentation on the metrics system, see the [Usage Metrics Documentation](docs/usage_metrics/README.md).
+
 ### How does CommitLoom handle large changes?
 
 CommitLoom automatically:

docs/usage_metrics/README.md

@@ -0,0 +1,93 @@
+# CommitLoom Usage Metrics
+
+CommitLoom now includes comprehensive usage metrics to help you understand your usage patterns, track costs, and measure productivity improvements.
+
+## Introduction
+
+The metrics system is designed to be:
+- **Private**: All data is stored locally; nothing is sent to external servers
+- **Transparent**: Clear data collection with easy access to view your metrics
+- **Useful**: Provides insights about cost savings, time saved, and usage patterns
+
+## Available Metrics
+
+CommitLoom tracks the following metrics:
+
+### Basic Metrics
+- Total commits generated
+- Total tokens used
+- Total cost in EUR
+- Total files processed
+- Estimated time saved
+
+### Repository Metrics
+- Most active repositories
+- Usage frequency by repository
+- File changes by repository
+
+### Model Usage Metrics
+- Token usage by model
+- Cost breakdown by model
+- Efficiency metrics (tokens per commit, cost per file)
+
+### Processing Metrics
+- Batch vs. single commits
+- Average processing time
+- Success rates
+
+## Viewing Metrics
+
+To view your metrics, use the `stats` command:
+
+```bash
+loom stats
+```
+
+This will display a summary of your usage statistics. To see more detailed information, you can use the debug flag:
+
+```bash
+loom stats -d
+```
+
+## Data Storage
+
+Metrics are stored locally in the following location, based on your operating system:
+
+- **Linux**: `~/.local/share/commitloom/metrics/`
+- **macOS**: `~/Library/Application Support/commitloom/metrics/`
+- **Windows**: `%APPDATA%\commitloom\metrics\`
+
+The data is stored in two JSON files:
+- `commit_metrics.json`: Contains detailed information about each commit
+- `usage_statistics.json`: Contains aggregated statistics about your usage
+
+## Privacy
+
+CommitLoom respects your privacy:
+- No telemetry or data collection occurs without your knowledge
+- All metrics are stored locally on your machine
+- No data is ever sent to external servers
+- You can delete the metrics files at any time to reset your statistics
+
+## How Time Savings Are Calculated
+
+CommitLoom estimates time savings based on the assumption that writing a quality commit message manually takes approximately 3 minutes on average. The time saved is calculated as:
+
+```
+time_saved = estimated_manual_time - actual_processing_time
+```
+
+Where:
+- `estimated_manual_time` is 3 minutes (180 seconds)
+- `actual_processing_time` is the time taken by CommitLoom to generate the commit message
+
+This provides a conservative estimate of how much time you're saving by using CommitLoom.
+
+## Future Enhancements
+
+In future versions, we plan to enhance the metrics system with:
+- Interactive visualizations
+- Export capabilities (CSV, JSON)
+- More detailed analysis by file type
+- Team-based aggregated statistics (while maintaining privacy)
+- Integration with development workflows and productivity tools