# Saini 🚀
[](https://badge.fury.io/py/saini)
[](https://pypi.org/project/saini/)
[](https://opensource.org/licenses/MIT)
[](https://pepy.tech/project/saini)
**Developer productivity toolkit by Rohit Saini**
Saini is a comprehensive command-line toolkit designed to boost developer productivity with intelligent time tracking, beautiful project visualization, and automation tools.
## ✨ Features
### ⏱️ Smart Time Tracking
- **Automatic Detection**: Auto-detect project and branch from git
- **Multi-Project Support**: Track time across multiple projects seamlessly
- **Pause/Resume**: Take breaks without losing context
- **Rich Reports**: Daily, weekly, and project-based analytics
- **Data Export**: Export to CSV or JSON for further analysis
### 🍅 Pomodoro Timer
- **Focus Sessions**: 25-minute work intervals with 5-minute breaks
- **Long Breaks**: Automatic 15-minute breaks after 4 pomodoros
- **Desktop Notifications**: Get notified when it's time for a break
- **Session Tracking**: Integrated with time tracking
### 👁️ Idle Detection
- **Smart Pause**: Auto-pause when no git activity detected
- **Configurable Threshold**: Set your own idle timeout (default: 10 minutes)
- **Activity Monitoring**: Tracks git commits and file changes
- **Seamless Resume**: Pick up right where you left off
### 🌳 Project Tree Visualization
- **Beautiful Output**: Rich, colorful tree structure with icons
- **Smart Filtering**: Auto-ignore node_modules, .git, build artifacts
- **File Information**: Optional file sizes and statistics
- **Multiple Formats**: Export to text or JSON
- **Customizable Depth**: Control how deep to traverse
- **Hidden Files**: Optionally show/hide hidden files
## 📦 Installation
### From PyPI (Recommended)
```bash
pip install saini
```
### From Source
```bash
git clone https://github.com/rohitsainier/saini.git
cd saini
./install.sh
```
### Upgrade
```bash
pip install --upgrade saini
```
## 🚀 Quick Start
### Time Tracking
```bash
# Start tracking your work
saini start "Implementing user authentication"
# Check current status
saini status
# Take a break
saini pause
# Resume work
saini resume
# Stop tracking
saini stop
# View today's report
saini report today
```
### Project Tree
```bash
# Show project structure
saini tree
# Limit depth to 3 levels
saini tree -d 3
# Show file sizes
saini tree -s
# Save to file
saini tree -o project-structure.txt
# Export as JSON
saini tree -o structure.json -f json
```
### Configuration
```bash
# Enable Pomodoro mode (25min work, 5min break)
saini config pomodoro on
# Enable idle detection
saini config idle on
# Set idle threshold to 15 minutes
saini config idle-time 15
# View all settings
saini config show
```
## 📚 Complete Command Reference
### Time Tracking Commands
| Command | Description | Example |
|---------|-------------|---------|
| `saini start [description]` | Start tracking time | `saini start "Bug fix #123"` |
| `saini stop` | Stop current session | `saini stop` |
| `saini switch [description]` | Switch to new task | `saini switch "Code review"` |
| `saini pause` | Pause current session | `saini pause` |
| `saini resume` | Resume paused session | `saini resume` |
| `saini status` | Show current status | `saini status` |
### Report Commands
| Command | Description | Example |
|---------|-------------|---------|
| `saini report today` | Today's activity | `saini report today` |
| `saini report yesterday` | Yesterday's activity | `saini report yesterday` |
| `saini report week` | This week's summary | `saini report week` |
| `saini report project [name]` | Project-specific report | `saini report project my-app` |
| `saini export csv [file]` | Export to CSV | `saini export csv report.csv` |
| `saini export json [file]` | Export to JSON | `saini export json report.json` |
### Configuration Commands
| Command | Description | Example |
|---------|-------------|---------|
| `saini config show` | Show all settings | `saini config show` |
| `saini config pomodoro [on\|off]` | Toggle Pomodoro timer | `saini config pomodoro on` |
| `saini config idle [on\|off]` | Toggle idle detection | `saini config idle on` |
| `saini config idle-time [min]` | Set idle threshold | `saini config idle-time 15` |
### Project Tree Commands
| Command | Description | Example |
|---------|-------------|---------|
| `saini tree` | Show project tree | `saini tree` |
| `saini tree -p [path]` | Specify custom path | `saini tree -p /path/to/project` |
| `saini tree -d [depth]` | Limit depth | `saini tree -d 3` |
| `saini tree -a` | Show hidden files | `saini tree -a` |
| `saini tree -s` | Show file sizes | `saini tree -s` |
| `saini tree -o [file]` | Save to file | `saini tree -o tree.txt` |
| `saini tree -f [format]` | Output format (text\|json) | `saini tree -f json` |
| `saini tree -i [pattern]` | Ignore pattern | `saini tree -i "*.log"` |
| `saini tree --no-icons` | Disable icons | `saini tree --no-icons` |
## 💡 Usage Examples
### Example 1: Daily Development Workflow
```bash
# Morning - Start your day
saini config pomodoro on
saini start "Sprint planning and standup"
# Check what you're tracking
saini status
# Output:
# ⚡ Active Session
# Project: my-awesome-app
# Branch: feature/user-auth
# Task: Sprint planning and standup
# Duration: 15m 30s
# 🍅 Pomodoro: Work Session #1
# Time Left: 9m 30s
# Switch to coding
saini switch "Implementing JWT authentication"
# Lunch break
saini pause
# Back from lunch
saini resume
# End of day - see what you accomplished
saini stop
saini report today
```
### Example 2: Project Analysis
```bash
# Understand project structure
saini tree -s -d 3
# Output:
# 📁 my-awesome-app
# ├── 📁 src
# │ ├── 📁 components
# │ │ ├── ⚛️ Header.jsx [2.3KB]
# │ │ └── ⚛️ Footer.jsx [1.8KB]
# │ ├── 🐍 main.py [5.2KB]
# │ └── 📋 config.json [892B]
# ├── 📁 tests
# │ └── 🐍 test_main.py [3.1KB]
# ├── 📝 README.md [4.5KB]
# └── 📋 package.json [1.2KB]
#
# 📊 3 directories, 8 files, Total size: 19.0KB
# Save for documentation
saini tree -o STRUCTURE.md
# Export as JSON for analysis
saini tree -o structure.json -f json
# Analyze only source code (ignore build files)
saini tree -i "dist" -i "node_modules" -i "*.min.js"
```
### Example 3: Weekly Review
```bash
# See weekly summary
saini report week
# Output:
# ═══════════════════════════════════════════════════
# Time Tracking Report
# ═══════════════════════════════════════════════════
#
# 📅 This Week (starting 2024-01-15)
#
# By Project:
# my-awesome-app 12h 30m
# client-website 8h 45m
# saini-package 5h 20m
#
# Total: 26h 35m
# Export for timesheet
saini export csv
```
### Example 4: Multi-Project Development
```bash
# Working on project A
cd ~/projects/project-a
saini start "Feature development"
# Switch to project B (auto-detects new project)
cd ~/projects/project-b
saini switch "Bug fix"
# Check time per project
saini report project project-a
saini report project project-b
```
### Example 5: Pomodoro Power User
```bash
# Enable Pomodoro with idle detection
saini config pomodoro on
saini config idle on
saini config idle-time 10
# Start focused work
saini start "Deep work - algorithm optimization"
# You'll get notifications:
# After 25 min: "Pomodoro Complete! 🍅 Time for a break! (5 min)"
# After 5 min break: "Break Over! ⏰ Ready to focus?"
# If idle for 10 min: "Auto-Paused ⏸ No git activity for 10m"
# Check status anytime
saini status
# Output:
# ⚡ Active Session
# Project: algorithm-lab
# Branch: optimization
# Task: Deep work - algorithm optimization
# Duration: 1h 45m 30s
# 🍅 Pomodoro: Work Session #5
# Time Left: 18m 12s
```
## 🎨 Screenshots
### Time Tracking Status
```
⚡ Active Session
Project: saini
Branch: main
Task: Adding tree visualization feature
Started: 2024-01-15 10:00:00
Duration: 45m 30s
🍅 Pomodoro: Work Session #2
Time Left: 12m 15s
```
### Project Tree
```
📁 saini
├── 📁 saini
│ ├── 🐍 __init__.py
│ ├── 🐍 cli.py
│ ├── 🐍 tracker.py
│ ├── 🐍 pomodoro.py
│ ├── 🐍 idle_detection.py
│ ├── 🐍 reports.py
│ ├── 🐍 config.py
│ ├── 🐍 tree.py
│ └── 🐍 utils.py
├── 📝 README.md
├── 📋 setup.py
├── 📋 requirements.txt
├── 🔧 install.sh
└── 🔧 publish.sh
📊 2 directories, 13 files
```
### Configuration
```
╔════════════════════════════════════════════╗
║ Time Tracker Configuration ║
╚════════════════════════════════════════════╝
Setting Value
─────────────────────────────────────────────
Pomodoro Mode ✓ Enabled
Pomodoro Work Time 25 minutes
Pomodoro Break Time 5 minutes
Pomodoro Long Break 15 minutes
Idle Detection ✓ Enabled
Idle Threshold 10 minutes
```
## ⚙️ Configuration
Configuration is stored in `~/.saini/config.json`:
```json
{
"pomodoro_enabled": true,
"pomodoro_work_time": 1500,
"pomodoro_break_time": 300,
"pomodoro_long_break": 900,
"idle_detection_enabled": true,
"idle_threshold": 600
}
```
### Data Storage
All data is stored in `~/.saini/`:
- `sessions.csv` - Time tracking sessions
- `config.json` - User configuration
- `current_session` - Active session data
- `paused_session` - Paused session data
- `pomodoro_state` - Pomodoro timer state
- `idle_check` - Idle detection state
## 🔧 Development
### Local Installation
```bash
# Clone the repository
git clone https://github.com/rohitsainier/saini.git
cd saini
# Install in development mode
./install.sh
# Or use Make
make install
```
### Running Tests
```bash
# Install test dependencies
pip install pytest pytest-cov
# Run tests
pytest tests/
# With coverage
pytest --cov=saini tests/
```
### Building the Package
```bash
# Build
./install.sh -c
python -m build
# Or use Make
make build
```
### Publishing
```bash
# Test publish (TestPyPI)
./publish.sh -t
# Production publish (PyPI)
./publish.sh
# With version bump
./publish.sh -v patch # 1.0.0 -> 1.0.1
./publish.sh -v minor # 1.0.0 -> 1.1.0
./publish.sh -v major # 1.0.0 -> 2.0.0
# Or use Make
make test-publish
make publish
```
## 🛠️ Makefile Commands
```bash
make install # Install package locally
make reinstall # Reinstall package
make clean # Clean build artifacts
make test # Run tests
make build # Build package
make test-publish # Publish to TestPyPI
make publish # Publish to PyPI
make version-patch # Bump patch version
make version-minor # Bump minor version
make version-major # Bump major version
```
## 📋 Requirements
- Python >= 3.7
- Git (for project/branch detection and idle detection)
- Dependencies:
- click >= 8.0.0
- rich >= 10.0.0
- gitpython >= 3.1.0
- pandas >= 1.3.0
- tabulate >= 0.8.9
## 🐛 Troubleshooting
### Issue: Command not found after installation
```bash
# Make sure pip bin directory is in PATH
export PATH="$HOME/.local/bin:$PATH"
# Add to ~/.bashrc or ~/.zshrc for persistence
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
```
### Issue: Notifications not working
**macOS**: Notifications should work out of the box.
**Linux**: Install `notify-send`:
```bash
sudo apt-get install libnotify-bin # Ubuntu/Debian
sudo yum install libnotify # Fedora/CentOS
```
**Windows**: Notifications are shown in terminal.
### Issue: Git detection not working
```bash
# Make sure you're in a git repository
git init
# Or specify path explicitly
saini tree -p /path/to/git/repo
```
### Issue: Permission denied on install
```bash
# Use pip with --user flag
pip install --user saini
# Or use sudo (not recommended)
sudo pip install saini
```
## 🗺️ Roadmap
### Version 1.x
- [x] Time tracking with pause/resume
- [x] Pomodoro timer with notifications
- [x] Idle detection
- [x] Project tree visualization
- [x] Multiple report formats
- [x] CSV/JSON export
### Version 2.x (Planned)
- [ ] `.gitignore` aware tree generation
- [ ] Code complexity analysis
- [ ] Duplicate code detection
- [ ] Dead code finder
- [ ] Unused dependency detection
- [ ] Integration with Jira/GitHub Issues
- [ ] Team collaboration features
- [ ] Cloud sync for time tracking
- [ ] Web dashboard
- [ ] Custom tree themes
- [ ] Tree diff between git commits
- [ ] AI-powered time estimation
- [ ] Automatic time categorization
## 🤝 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. **Make your changes**
4. **Install and test**: `./install.sh -r`
5. **Commit your changes**: `git commit -m 'Add amazing feature'`
6. **Push to the branch**: `git push origin feature/amazing-feature`
7. **Open a Pull Request**
### Development Guidelines
- Follow PEP 8 style guide
- Add tests for new features
- Update documentation
- Run tests before submitting PR
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 👨💻 Author
**Rohit Saini**
- GitHub: [@rohitsainier](https://github.com/rohitsainier)
- Email: rohitsainier@example.com
- Twitter: [@rohitsainier](https://twitter.com/rohitsainier)
## 🙏 Acknowledgments
- Inspired by the need for better developer productivity tools
- Built with [Click](https://click.palletsprojects.com/) and [Rich](https://rich.readthedocs.io/)
- Thanks to all contributors and users!
## 📊 Stats
## 💬 Support
- **Issues**: [GitHub Issues](https://github.com/rohitsainier/saini/issues)
- **Discussions**: [GitHub Discussions](https://github.com/rohitsainier/saini/discussions)
- **Email**: rohitsainier@example.com
## 🌟 Star History
If you find Saini useful, please consider giving it a star! ⭐
## 📈 Changelog
### Version 1.0.0 (2024-01-15)
- Initial release
- Time tracking with pause/resume
- Pomodoro timer integration
- Idle detection
- Project tree visualization
- Report generation (today, yesterday, week)
- CSV/JSON export
- Configuration management
- Beautiful CLI with Rich
- Installation and publishing scripts
---
**Made with ❤️ by Rohit Saini**
*Boost your productivity, one commit at a time!*
```
## Additional Documentation Files
### `CONTRIBUTING.md`
```markdown
# Contributing to Saini
Thank you for your interest in contributing to Saini! 🎉
## Getting Started
1. Fork the repository
2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/saini.git`
3. Create a branch: `git checkout -b feature/your-feature`
4. Make your changes
5. Test your changes: `./install.sh -r && pytest`
6. Commit: `git commit -m 'Add some feature'`
7. Push: `git push origin feature/your-feature`
8. Open a Pull Request
## Development Setup
```bash
# Install in development mode
./install.sh
# Install dev dependencies
pip install pytest pytest-cov black flake8 mypy
# Run tests
pytest tests/
# Format code
black saini/
# Lint
flake8 saini/
```
## Code Style
- Follow PEP 8
- Use Black for formatting
- Add docstrings to all functions
- Write tests for new features
## Pull Request Guidelines
- Update README.md if needed
- Add tests for new features
- Ensure all tests pass
- Update CHANGELOG.md
## Questions?
Open an issue or discussion!
```
### `CHANGELOG.md`
```markdown
# Changelog
All notable changes to this project will be documented in this file.
## [1.0.0] - 2024-01-15
### Added
- Initial release
- Time tracking functionality
- Pomodoro timer with desktop notifications
- Idle detection based on git activity
- Project tree visualization with icons
- Multiple report formats (today, yesterday, week, project)
- CSV and JSON export
- Configuration management
- Beautiful CLI with Rich library
- Installation script (install.sh)
- Publishing script (publish.sh)
- Makefile for common tasks
### Features
- Auto-detect project and branch from git
- Pause/resume time tracking
- 25-minute Pomodoro sessions with 5-minute breaks
- Customizable idle detection threshold
- File size information in tree view
- Export tree to text or JSON
- Comprehensive documentation
## [Unreleased]
### Planned
- .gitignore aware tree
- Code complexity analysis
- Duplicate code detection
- Integration with GitHub/Jira
- Team collaboration features
```
Now you have a complete, professional README! 🚀
Want me to create any other documentation files like:
- API documentation
- Architecture diagram
- Tutorial/Guide
- FAQ section?
Raw data
{
"_id": null,
"home_page": "https://github.com/rohitsainier/saini",
"name": "saini",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.7",
"maintainer_email": null,
"keywords": "git time-tracking pomodoro productivity developer-tools project-tree cli automation",
"author": "Rohit Saini",
"author_email": "rohitsainier@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/66/d7/d4514223b0c984c7a7b3e10aed14a0cc62dd7a467d5e65a5b714e5b4f245/saini-1.0.5.tar.gz",
"platform": null,
"description": "# Saini \ud83d\ude80\n\n[](https://badge.fury.io/py/saini)\n[](https://pypi.org/project/saini/)\n[](https://opensource.org/licenses/MIT)\n[](https://pepy.tech/project/saini)\n\n**Developer productivity toolkit by Rohit Saini**\n\nSaini is a comprehensive command-line toolkit designed to boost developer productivity with intelligent time tracking, beautiful project visualization, and automation tools.\n\n## \u2728 Features\n\n### \u23f1\ufe0f Smart Time Tracking\n- **Automatic Detection**: Auto-detect project and branch from git\n- **Multi-Project Support**: Track time across multiple projects seamlessly\n- **Pause/Resume**: Take breaks without losing context\n- **Rich Reports**: Daily, weekly, and project-based analytics\n- **Data Export**: Export to CSV or JSON for further analysis\n\n### \ud83c\udf45 Pomodoro Timer\n- **Focus Sessions**: 25-minute work intervals with 5-minute breaks\n- **Long Breaks**: Automatic 15-minute breaks after 4 pomodoros\n- **Desktop Notifications**: Get notified when it's time for a break\n- **Session Tracking**: Integrated with time tracking\n\n### \ud83d\udc41\ufe0f Idle Detection\n- **Smart Pause**: Auto-pause when no git activity detected\n- **Configurable Threshold**: Set your own idle timeout (default: 10 minutes)\n- **Activity Monitoring**: Tracks git commits and file changes\n- **Seamless Resume**: Pick up right where you left off\n\n### \ud83c\udf33 Project Tree Visualization\n- **Beautiful Output**: Rich, colorful tree structure with icons\n- **Smart Filtering**: Auto-ignore node_modules, .git, build artifacts\n- **File Information**: Optional file sizes and statistics\n- **Multiple Formats**: Export to text or JSON\n- **Customizable Depth**: Control how deep to traverse\n- **Hidden Files**: Optionally show/hide hidden files\n\n## \ud83d\udce6 Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install saini\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/rohitsainier/saini.git\ncd saini\n./install.sh\n```\n\n### Upgrade\n\n```bash\npip install --upgrade saini\n```\n\n## \ud83d\ude80 Quick Start\n\n### Time Tracking\n\n```bash\n# Start tracking your work\nsaini start \"Implementing user authentication\"\n\n# Check current status\nsaini status\n\n# Take a break\nsaini pause\n\n# Resume work\nsaini resume\n\n# Stop tracking\nsaini stop\n\n# View today's report\nsaini report today\n```\n\n### Project Tree\n\n```bash\n# Show project structure\nsaini tree\n\n# Limit depth to 3 levels\nsaini tree -d 3\n\n# Show file sizes\nsaini tree -s\n\n# Save to file\nsaini tree -o project-structure.txt\n\n# Export as JSON\nsaini tree -o structure.json -f json\n```\n\n### Configuration\n\n```bash\n# Enable Pomodoro mode (25min work, 5min break)\nsaini config pomodoro on\n\n# Enable idle detection\nsaini config idle on\n\n# Set idle threshold to 15 minutes\nsaini config idle-time 15\n\n# View all settings\nsaini config show\n```\n\n## \ud83d\udcda Complete Command Reference\n\n### Time Tracking Commands\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `saini start [description]` | Start tracking time | `saini start \"Bug fix #123\"` |\n| `saini stop` | Stop current session | `saini stop` |\n| `saini switch [description]` | Switch to new task | `saini switch \"Code review\"` |\n| `saini pause` | Pause current session | `saini pause` |\n| `saini resume` | Resume paused session | `saini resume` |\n| `saini status` | Show current status | `saini status` |\n\n### Report Commands\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `saini report today` | Today's activity | `saini report today` |\n| `saini report yesterday` | Yesterday's activity | `saini report yesterday` |\n| `saini report week` | This week's summary | `saini report week` |\n| `saini report project [name]` | Project-specific report | `saini report project my-app` |\n| `saini export csv [file]` | Export to CSV | `saini export csv report.csv` |\n| `saini export json [file]` | Export to JSON | `saini export json report.json` |\n\n### Configuration Commands\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `saini config show` | Show all settings | `saini config show` |\n| `saini config pomodoro [on\\|off]` | Toggle Pomodoro timer | `saini config pomodoro on` |\n| `saini config idle [on\\|off]` | Toggle idle detection | `saini config idle on` |\n| `saini config idle-time [min]` | Set idle threshold | `saini config idle-time 15` |\n\n### Project Tree Commands\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `saini tree` | Show project tree | `saini tree` |\n| `saini tree -p [path]` | Specify custom path | `saini tree -p /path/to/project` |\n| `saini tree -d [depth]` | Limit depth | `saini tree -d 3` |\n| `saini tree -a` | Show hidden files | `saini tree -a` |\n| `saini tree -s` | Show file sizes | `saini tree -s` |\n| `saini tree -o [file]` | Save to file | `saini tree -o tree.txt` |\n| `saini tree -f [format]` | Output format (text\\|json) | `saini tree -f json` |\n| `saini tree -i [pattern]` | Ignore pattern | `saini tree -i \"*.log\"` |\n| `saini tree --no-icons` | Disable icons | `saini tree --no-icons` |\n\n## \ud83d\udca1 Usage Examples\n\n### Example 1: Daily Development Workflow\n\n```bash\n# Morning - Start your day\nsaini config pomodoro on\nsaini start \"Sprint planning and standup\"\n\n# Check what you're tracking\nsaini status\n# Output:\n# \u26a1 Active Session\n# Project: my-awesome-app\n# Branch: feature/user-auth\n# Task: Sprint planning and standup\n# Duration: 15m 30s\n# \ud83c\udf45 Pomodoro: Work Session #1\n# Time Left: 9m 30s\n\n# Switch to coding\nsaini switch \"Implementing JWT authentication\"\n\n# Lunch break\nsaini pause\n\n# Back from lunch\nsaini resume\n\n# End of day - see what you accomplished\nsaini stop\nsaini report today\n```\n\n### Example 2: Project Analysis\n\n```bash\n# Understand project structure\nsaini tree -s -d 3\n\n# Output:\n# \ud83d\udcc1 my-awesome-app\n# \u251c\u2500\u2500 \ud83d\udcc1 src\n# \u2502 \u251c\u2500\u2500 \ud83d\udcc1 components\n# \u2502 \u2502 \u251c\u2500\u2500 \u269b\ufe0f Header.jsx [2.3KB]\n# \u2502 \u2502 \u2514\u2500\u2500 \u269b\ufe0f Footer.jsx [1.8KB]\n# \u2502 \u251c\u2500\u2500 \ud83d\udc0d main.py [5.2KB]\n# \u2502 \u2514\u2500\u2500 \ud83d\udccb config.json [892B]\n# \u251c\u2500\u2500 \ud83d\udcc1 tests\n# \u2502 \u2514\u2500\u2500 \ud83d\udc0d test_main.py [3.1KB]\n# \u251c\u2500\u2500 \ud83d\udcdd README.md [4.5KB]\n# \u2514\u2500\u2500 \ud83d\udccb package.json [1.2KB]\n#\n# \ud83d\udcca 3 directories, 8 files, Total size: 19.0KB\n\n# Save for documentation\nsaini tree -o STRUCTURE.md\n\n# Export as JSON for analysis\nsaini tree -o structure.json -f json\n\n# Analyze only source code (ignore build files)\nsaini tree -i \"dist\" -i \"node_modules\" -i \"*.min.js\"\n```\n\n### Example 3: Weekly Review\n\n```bash\n# See weekly summary\nsaini report week\n\n# Output:\n# \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n# Time Tracking Report\n# \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n# \n# \ud83d\udcc5 This Week (starting 2024-01-15)\n# \n# By Project:\n# my-awesome-app 12h 30m\n# client-website 8h 45m\n# saini-package 5h 20m\n# \n# Total: 26h 35m\n\n# Export for timesheet\nsaini export csv \n```\n\n### Example 4: Multi-Project Development\n\n```bash\n# Working on project A\ncd ~/projects/project-a\nsaini start \"Feature development\"\n\n# Switch to project B (auto-detects new project)\ncd ~/projects/project-b\nsaini switch \"Bug fix\"\n\n# Check time per project\nsaini report project project-a\nsaini report project project-b\n```\n\n### Example 5: Pomodoro Power User\n\n```bash\n# Enable Pomodoro with idle detection\nsaini config pomodoro on\nsaini config idle on\nsaini config idle-time 10\n\n# Start focused work\nsaini start \"Deep work - algorithm optimization\"\n\n# You'll get notifications:\n# After 25 min: \"Pomodoro Complete! \ud83c\udf45 Time for a break! (5 min)\"\n# After 5 min break: \"Break Over! \u23f0 Ready to focus?\"\n# If idle for 10 min: \"Auto-Paused \u23f8 No git activity for 10m\"\n\n# Check status anytime\nsaini status\n# Output:\n# \u26a1 Active Session\n# Project: algorithm-lab\n# Branch: optimization\n# Task: Deep work - algorithm optimization\n# Duration: 1h 45m 30s\n# \ud83c\udf45 Pomodoro: Work Session #5\n# Time Left: 18m 12s\n```\n\n## \ud83c\udfa8 Screenshots\n\n### Time Tracking Status\n```\n\u26a1 Active Session\n Project: saini\n Branch: main\n Task: Adding tree visualization feature\n Started: 2024-01-15 10:00:00\n Duration: 45m 30s\n \ud83c\udf45 Pomodoro: Work Session #2\n Time Left: 12m 15s\n```\n\n### Project Tree\n```\n\ud83d\udcc1 saini\n\u251c\u2500\u2500 \ud83d\udcc1 saini\n\u2502 \u251c\u2500\u2500 \ud83d\udc0d __init__.py\n\u2502 \u251c\u2500\u2500 \ud83d\udc0d cli.py\n\u2502 \u251c\u2500\u2500 \ud83d\udc0d tracker.py\n\u2502 \u251c\u2500\u2500 \ud83d\udc0d pomodoro.py\n\u2502 \u251c\u2500\u2500 \ud83d\udc0d idle_detection.py\n\u2502 \u251c\u2500\u2500 \ud83d\udc0d reports.py\n\u2502 \u251c\u2500\u2500 \ud83d\udc0d config.py\n\u2502 \u251c\u2500\u2500 \ud83d\udc0d tree.py\n\u2502 \u2514\u2500\u2500 \ud83d\udc0d utils.py\n\u251c\u2500\u2500 \ud83d\udcdd README.md\n\u251c\u2500\u2500 \ud83d\udccb setup.py\n\u251c\u2500\u2500 \ud83d\udccb requirements.txt\n\u251c\u2500\u2500 \ud83d\udd27 install.sh\n\u2514\u2500\u2500 \ud83d\udd27 publish.sh\n\n\ud83d\udcca 2 directories, 13 files\n```\n\n### Configuration\n```\n\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557\n\u2551 Time Tracker Configuration \u2551\n\u255a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255d\n\nSetting Value\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nPomodoro Mode \u2713 Enabled\nPomodoro Work Time 25 minutes\nPomodoro Break Time 5 minutes\nPomodoro Long Break 15 minutes\nIdle Detection \u2713 Enabled\nIdle Threshold 10 minutes\n```\n\n\n## \u2699\ufe0f Configuration\n\nConfiguration is stored in `~/.saini/config.json`:\n\n```json\n{\n \"pomodoro_enabled\": true,\n \"pomodoro_work_time\": 1500,\n \"pomodoro_break_time\": 300,\n \"pomodoro_long_break\": 900,\n \"idle_detection_enabled\": true,\n \"idle_threshold\": 600\n}\n```\n\n### Data Storage\n\nAll data is stored in `~/.saini/`:\n- `sessions.csv` - Time tracking sessions\n- `config.json` - User configuration\n- `current_session` - Active session data\n- `paused_session` - Paused session data\n- `pomodoro_state` - Pomodoro timer state\n- `idle_check` - Idle detection state\n\n## \ud83d\udd27 Development\n\n### Local Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/rohitsainier/saini.git\ncd saini\n\n# Install in development mode\n./install.sh\n\n# Or use Make\nmake install\n```\n\n### Running Tests\n\n```bash\n# Install test dependencies\npip install pytest pytest-cov\n\n# Run tests\npytest tests/\n\n# With coverage\npytest --cov=saini tests/\n```\n\n### Building the Package\n\n```bash\n# Build\n./install.sh -c\npython -m build\n\n# Or use Make\nmake build\n```\n\n### Publishing\n\n```bash\n# Test publish (TestPyPI)\n./publish.sh -t\n\n# Production publish (PyPI)\n./publish.sh\n\n# With version bump\n./publish.sh -v patch # 1.0.0 -> 1.0.1\n./publish.sh -v minor # 1.0.0 -> 1.1.0\n./publish.sh -v major # 1.0.0 -> 2.0.0\n\n# Or use Make\nmake test-publish\nmake publish\n```\n\n## \ud83d\udee0\ufe0f Makefile Commands\n\n```bash\nmake install # Install package locally\nmake reinstall # Reinstall package\nmake clean # Clean build artifacts\nmake test # Run tests\nmake build # Build package\nmake test-publish # Publish to TestPyPI\nmake publish # Publish to PyPI\nmake version-patch # Bump patch version\nmake version-minor # Bump minor version\nmake version-major # Bump major version\n```\n\n## \ud83d\udccb Requirements\n\n- Python >= 3.7\n- Git (for project/branch detection and idle detection)\n- Dependencies:\n - click >= 8.0.0\n - rich >= 10.0.0\n - gitpython >= 3.1.0\n - pandas >= 1.3.0\n - tabulate >= 0.8.9\n\n## \ud83d\udc1b Troubleshooting\n\n### Issue: Command not found after installation\n\n```bash\n# Make sure pip bin directory is in PATH\nexport PATH=\"$HOME/.local/bin:$PATH\"\n\n# Add to ~/.bashrc or ~/.zshrc for persistence\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.bashrc\n```\n\n### Issue: Notifications not working\n\n**macOS**: Notifications should work out of the box.\n\n**Linux**: Install `notify-send`:\n```bash\nsudo apt-get install libnotify-bin # Ubuntu/Debian\nsudo yum install libnotify # Fedora/CentOS\n```\n\n**Windows**: Notifications are shown in terminal.\n\n### Issue: Git detection not working\n\n```bash\n# Make sure you're in a git repository\ngit init\n\n# Or specify path explicitly\nsaini tree -p /path/to/git/repo\n```\n\n### Issue: Permission denied on install\n\n```bash\n# Use pip with --user flag\npip install --user saini\n\n# Or use sudo (not recommended)\nsudo pip install saini\n```\n\n## \ud83d\uddfa\ufe0f Roadmap\n\n### Version 1.x\n- [x] Time tracking with pause/resume\n- [x] Pomodoro timer with notifications\n- [x] Idle detection\n- [x] Project tree visualization\n- [x] Multiple report formats\n- [x] CSV/JSON export\n\n### Version 2.x (Planned)\n- [ ] `.gitignore` aware tree generation\n- [ ] Code complexity analysis\n- [ ] Duplicate code detection\n- [ ] Dead code finder\n- [ ] Unused dependency detection\n- [ ] Integration with Jira/GitHub Issues\n- [ ] Team collaboration features\n- [ ] Cloud sync for time tracking\n- [ ] Web dashboard\n- [ ] Custom tree themes\n- [ ] Tree diff between git commits\n- [ ] AI-powered time estimation\n- [ ] Automatic time categorization\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Here's how you can help:\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/amazing-feature`\n3. **Make your changes**\n4. **Install and test**: `./install.sh -r`\n5. **Commit your changes**: `git commit -m 'Add amazing feature'`\n6. **Push to the branch**: `git push origin feature/amazing-feature`\n7. **Open a Pull Request**\n\n### Development Guidelines\n\n- Follow PEP 8 style guide\n- Add tests for new features\n- Update documentation\n- Run tests before submitting PR\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udc68\u200d\ud83d\udcbb Author\n\n**Rohit Saini**\n\n- GitHub: [@rohitsainier](https://github.com/rohitsainier)\n- Email: rohitsainier@example.com\n- Twitter: [@rohitsainier](https://twitter.com/rohitsainier)\n\n## \ud83d\ude4f Acknowledgments\n\n- Inspired by the need for better developer productivity tools\n- Built with [Click](https://click.palletsprojects.com/) and [Rich](https://rich.readthedocs.io/)\n- Thanks to all contributors and users!\n\n## \ud83d\udcca Stats\n\n\n\n\n\n## \ud83d\udcac Support\n\n- **Issues**: [GitHub Issues](https://github.com/rohitsainier/saini/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/rohitsainier/saini/discussions)\n- **Email**: rohitsainier@example.com\n\n## \ud83c\udf1f Star History\n\nIf you find Saini useful, please consider giving it a star! \u2b50\n\n## \ud83d\udcc8 Changelog\n\n### Version 1.0.0 (2024-01-15)\n- Initial release\n- Time tracking with pause/resume\n- Pomodoro timer integration\n- Idle detection\n- Project tree visualization\n- Report generation (today, yesterday, week)\n- CSV/JSON export\n- Configuration management\n- Beautiful CLI with Rich\n- Installation and publishing scripts\n\n---\n\n**Made with \u2764\ufe0f by Rohit Saini**\n\n*Boost your productivity, one commit at a time!*\n```\n\n## Additional Documentation Files\n\n### `CONTRIBUTING.md`\n\n```markdown\n# Contributing to Saini\n\nThank you for your interest in contributing to Saini! \ud83c\udf89\n\n## Getting Started\n\n1. Fork the repository\n2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/saini.git`\n3. Create a branch: `git checkout -b feature/your-feature`\n4. Make your changes\n5. Test your changes: `./install.sh -r && pytest`\n6. Commit: `git commit -m 'Add some feature'`\n7. Push: `git push origin feature/your-feature`\n8. Open a Pull Request\n\n## Development Setup\n\n```bash\n# Install in development mode\n./install.sh\n\n# Install dev dependencies\npip install pytest pytest-cov black flake8 mypy\n\n# Run tests\npytest tests/\n\n# Format code\nblack saini/\n\n# Lint\nflake8 saini/\n```\n\n## Code Style\n\n- Follow PEP 8\n- Use Black for formatting\n- Add docstrings to all functions\n- Write tests for new features\n\n## Pull Request Guidelines\n\n- Update README.md if needed\n- Add tests for new features\n- Ensure all tests pass\n- Update CHANGELOG.md\n\n## Questions?\n\nOpen an issue or discussion!\n```\n\n### `CHANGELOG.md`\n\n```markdown\n# Changelog\n\nAll notable changes to this project will be documented in this file.\n\n## [1.0.0] - 2024-01-15\n\n### Added\n- Initial release\n- Time tracking functionality\n- Pomodoro timer with desktop notifications\n- Idle detection based on git activity\n- Project tree visualization with icons\n- Multiple report formats (today, yesterday, week, project)\n- CSV and JSON export\n- Configuration management\n- Beautiful CLI with Rich library\n- Installation script (install.sh)\n- Publishing script (publish.sh)\n- Makefile for common tasks\n\n### Features\n- Auto-detect project and branch from git\n- Pause/resume time tracking\n- 25-minute Pomodoro sessions with 5-minute breaks\n- Customizable idle detection threshold\n- File size information in tree view\n- Export tree to text or JSON\n- Comprehensive documentation\n\n## [Unreleased]\n\n### Planned\n- .gitignore aware tree\n- Code complexity analysis\n- Duplicate code detection\n- Integration with GitHub/Jira\n- Team collaboration features\n```\n\nNow you have a complete, professional README! \ud83d\ude80\n\nWant me to create any other documentation files like:\n- API documentation\n- Architecture diagram\n- Tutorial/Guide\n- FAQ section?\n",
"bugtrack_url": null,
"license": null,
"summary": "Developer productivity toolkit: time tracking, Pomodoro timer, project tree visualization, and automation tools",
"version": "1.0.5",
"project_urls": {
"Bug Reports": "https://github.com/rohitsainier/saini/issues",
"Documentation": "https://github.com/rohitsainier/saini#readme",
"Homepage": "https://github.com/rohitsainier/saini",
"Source": "https://github.com/rohitsainier/saini"
},
"split_keywords": [
"git",
"time-tracking",
"pomodoro",
"productivity",
"developer-tools",
"project-tree",
"cli",
"automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "abe1e13261ce775c3c7259d90ebc91dbd24daf657217e13c49c87c4d985092d5",
"md5": "9da22c1b2a330766176ce0f7840c4afa",
"sha256": "63e443161b7ab160152cdb10ec272982c268dabd3651f7629c9cdc1e4f06e00b"
},
"downloads": -1,
"filename": "saini-1.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9da22c1b2a330766176ce0f7840c4afa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.7",
"size": 28553,
"upload_time": "2025-10-19T06:10:58",
"upload_time_iso_8601": "2025-10-19T06:10:58.864067Z",
"url": "https://files.pythonhosted.org/packages/ab/e1/e13261ce775c3c7259d90ebc91dbd24daf657217e13c49c87c4d985092d5/saini-1.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "66d7d4514223b0c984c7a7b3e10aed14a0cc62dd7a467d5e65a5b714e5b4f245",
"md5": "03217ad6909e3468419db90fb53e0ab1",
"sha256": "ff7161997ce664be27fe7116edec33ff431eec34b0bd05e118a5ef69bcc78256"
},
"downloads": -1,
"filename": "saini-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "03217ad6909e3468419db90fb53e0ab1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.7",
"size": 31469,
"upload_time": "2025-10-19T06:11:00",
"upload_time_iso_8601": "2025-10-19T06:11:00.530067Z",
"url": "https://files.pythonhosted.org/packages/66/d7/d4514223b0c984c7a7b3e10aed14a0cc62dd7a467d5e65a5b714e5b4f245/saini-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-19 06:11:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rohitsainier",
"github_project": "saini",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"10.0.0"
]
]
},
{
"name": "gitpython",
"specs": [
[
">=",
"3.1.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.3.0"
]
]
},
{
"name": "tabulate",
"specs": [
[
">=",
"0.8.9"
]
]
}
],
"lcname": "saini"
}
JSON
