⏱️ CLI Time Tracker for Freelancers

A robust, persistent command-line interface (CLI) tool built with Node.js to help freelancers track billable hours across multiple projects. It features real-time tracking, data persistence using a local JSON database, and advanced reporting capabilities.

Author: Mujeeb (https://github.com/Mujee-dot)

🚀 Features

• Session Management: Start and stop timers for specific projects.
• Data Persistence: All data is saved to a local data.json file, ensuring logs survive system restarts.
• Smart Reporting: Calculate total hours worked on a project.
• Time Filtering: Filter reports by date (e.g., "Show me work done since 2025-01-01").
• Project Discovery: List all projects ever worked on with a single command.
• Duplicate Handling: Prevents starting multiple concurrent timers for the same project.

🛠️ Tech Stack

• Runtime: Node.js
• Time Manipulation: Day.js (for Unix timestamp conversion and formatting)
• I/O: Node.js File System (fs) module
• Interface: Node.js Readline module

📦 Installation

1. Clone the repository

   git clone https://github.com/Mujee-dot/time-tracker-cli.git
   cd time-tracker-cli

2. Install Dependencies

   npm install

3. Run the Application

   node index.js

📖 Usage Guide

Once the CLI is running, use the following commands:

1. Start a Timer

Begins a new session. If a session is already open for this project, it will warn you.

> start [project-name]
Example: start website-redesign

2. Stop a Timer

Finds the active session for the project and closes it, saving the duration.

> stop [project-name]
Example: stop website-redesign

3. Generate Report

Shows total time and session count. You can optionally filter by date.

> report [project-name]
> report [project-name] since [YYYY-MM-DD]

Example: report website-redesign since 2025-01-01

4. List Projects

Displays a deduplicated list of all projects in the database.

> list

5. Exit

Saves data safely and closes the application.

> exit

🧩 How It Works (Architecture)

The application uses an Event Loop architecture via the readline module to listen for user input continuously.

• Data Structure: Data is stored as an array of objects in data.json:

  {
    "project": "design-work",
    "start": 1732946100,
    "end": 1732950000
  }

• Logic:
  • Timestamps: All time is stored as Unix Timestamps (Integers) for precise mathematical calculations.
  • Filtering: The report command uses functional programming (.filter(), .reduce()) to aggregate duration based on specific criteria.

🔮 Future Improvements

• Migrate from JSON file storage to SQLite for better scalability.
• Add an export command to save reports as CSV files.
• Add support for hourly rates to calculate billable amounts directly.

---

Contributing

1. Fork the repo
2. Create a feature branch
3. Open a pull request describing your changes

---

License

This repository is provided without an explicit license. Add one if you intend to make it open-source.