⏱️ Chrono Tracker

A powerful CLI tool for freelancers to track time spent on projects with detailed reporting

Installation • Quick Start • Commands • Features

🚀 Installation

# Install globally via npm
npm install -g chrono-tracker

# Or via yarn
yarn global add chrono-tracker

Requirements: Node.js >= 18.0.0

⚡ Quick Start

# Start tracking time for a project
chrono-tracker start "My Awesome Project"

# Check current status
chrono-tracker status

# Stop tracking
chrono-tracker stop "My Awesome Project"

# View detailed report
chrono-tracker report

✨ Features

🎯 Multi-Project Tracking
Track time for multiple projects simultaneously

📊 Detailed Reporting
Comprehensive reports with time breakdowns

💰 Earnings Calculation
Calculate potential earnings based on time spent

🎨 Beautiful CLI Interface
Professional formatting with colors and emojis

💾 Zero Setup Required
SQLite database automatically created

🔄 Cross-Platform
Works on Windows, macOS, and Linux

📖 Commands

chrono-tracker start <project-name>

Start tracking time for a project. Creates the project automatically if it doesn't exist.

chrono-tracker start "Client Website Redesign"
chrono-tracker start "Mobile App Development"

Output:

✅ Started tracking time for: Client Website Redesign
📍 Started at: 2024-01-15 09:30:00

chrono-tracker status

View all currently active time tracking sessions with live duration updates.

chrono-tracker status

Output:

🔥 Active Time Tracking Sessions:

📋 Project: Client Website Redesign
⏰ Started: 2024-01-15 09:30:00
⏱️  Duration: 2h 30m

📋 Project: Mobile App Development
⏰ Started: 2024-01-15 12:00:00
⏱️  Duration: 1h 15m

chrono-tracker stop <project-name>

Stop tracking time for an active project and save the session.

chrono-tracker stop "Client Website Redesign"

Output:

⏹️  Stopped tracking: Client Website Redesign
⏱️  Session duration: 2h 30m
💰 Potential earnings: $125.00 (at $50/hour)

chrono-tracker report [project-name]

Generate detailed time reports. Interactive project selection if no name provided.

# Interactive mode
chrono-tracker report

# Specific project report
chrono-tracker report "Client Website Redesign"

Output:

📊 Time Report for: Client Website Redesign

📅 Time Entries:
┌─────────────────────┬─────────────────────┬──────────┐
│ Start Time          │ End Time            │ Duration │
├─────────────────────┼─────────────────────┼──────────┤
│ 2024-01-15 09:30:00 │ 2024-01-15 12:00:00 │ 2h 30m   │
│ 2024-01-15 14:00:00 │ 2024-01-15 16:30:00 │ 2h 30m   │
└─────────────────────┴─────────────────────┴──────────┘

⏱️  Total Time: 5h 00m
💰 Potential Earnings: $250.00 (at $50/hour)

🏗️ Architecture

Built with modern technologies for reliability and performance:

• NestJS - Robust backend framework
• Prisma ORM - Type-safe database operations
• SQLite - Embedded database (zero setup)
• TypeScript - Type safety and better DX
• Commander.js - Professional CLI interface
• Day.js - Lightweight date manipulation

💾 Data Storage

Chrono Tracker automatically creates a local SQLite database:

• Development: ./dev.db (in project folder)
• Global Install: ~/.chrono-tracker/chrono-tracker.db (user home directory)

No configuration required! The database and tables are created automatically on first use.

📊 Usage Examples

Daily Workflow

# Morning: Start your main project
chrono-tracker start "Client A - Website"

# Switch to another project
chrono-tracker stop "Client A - Website"
chrono-tracker start "Client B - Mobile App"

# Check what's currently active
chrono-tracker status

# End of day: Stop tracking and review
chrono-tracker stop "Client B - Mobile App"
chrono-tracker report "Client A - Website"

Weekly Review

# Generate reports for all projects
chrono-tracker report "Client A - Website"
chrono-tracker report "Client B - Mobile App"
chrono-tracker report "Personal Project"

🔧 Development

Want to contribute? Here's how to set up the development environment:

# Clone the repository
git clone https://github.com/persuasivepost/chrono-tracker.git
cd chrono-tracker

# Install dependencies
yarn install

# Set up database
yarn db:generate

# Run in development mode
yarn cli:dev start "Test Project"

# Build for production
yarn build

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🐛 Support

• Issues: GitHub Issues
• Questions: GitHub Discussions

🌟 Show Your Support

If this project helped you, please consider giving it a ⭐ on GitHub!

Made with ❤️ for freelancers worldwide

⬆ Back to Top