track

Minimal CLI time tracker tool built with TypeScript and Bun.

Description

track is a lightweight command-line time tracker that helps you monitor how much time you spend on tasks. It uses a local CSV file to store tracking data in the current working directory, making it easy to track time across different projects.

Features:

• Start and stop time tracking with optional task titles
• Resume the last stopped timer with a single command
• Assign entries to projects with --project for organized tracking
• View current tracking status with elapsed time
• Watch mode with interactive keyboard controls (stop, resume, quit)
• Filter time entries by day, week, month, year, or all time
• Filter time entries by project
• Prevents multiple concurrent timers
• Stores data in a simple CSV format for easy access
• Tracks username, task title, project, start time, and end time
• Backward compatible with older CSV files (without project column)

Installation

Install from npm (Recommended)

Using npm:

npm install -g @heyimstas/timetracking

Using bun:

bun add -g @heyimstas/timetracking

The track command will now be available globally on your system.

Install from source

For development or if you want to modify the code:

Prerequisites: Bun must be installed on your system

1. Clone this repository:

git clone https://github.com/DrEverr/timetrack.git
cd timetrack

2. Install dependencies:

bun install

3. Build the project:

bun run build

4. Link the CLI globally:

bun link

The track command is now available globally on your system.

Usage

Start tracking

Start a timer without a title:

track start

Start a timer with a title:

track start "my task"

Start a timer with a project:

track start "my task" --project myproject
track start "my task" -p myproject

Start tracking with live timer display (watch mode):

track start "my task" --watch

You can also specify a custom refresh interval in seconds:

track start "my task" --watch 2

Stop tracking

Stop the currently running timer:

track stop

Resume tracking

Restart the last stopped timer with the same title and project:

track resume

You can also use the continue alias:

track continue

Resume with watch mode:

track resume --watch

Check status

View the current tracking status:

track status

If a timer is running, it will show the task title (if provided) and elapsed time. If no timer is running, it will display "Nothing is being tracked".

Watch mode (continuously refresh status):

track status --watch

You can also specify a custom refresh interval in seconds:

track status --watch 2

Watch mode keyboard controls

When using --watch with any command, interactive keyboard controls are available:

Key	Action
s	Stop the current timer
r	Resume the last stopped timer
q / Ctrl+C	Exit watch mode

List entries

Display a formatted table of time tracking entries. By default, shows entries for today:

track list

Filter entries by different time periods:

track list -d, --day     # Today's entries (default)
track list -w, --week    # This week's entries
track list -m, --month   # This month's entries
track list -y, --year    # This year's entries
track list -a, --all     # All entries

Filter entries by project:

track list --all --project myproject
track list -a -p myproject

You can combine project and date filters:

track list --week --project frontend

This command shows entries in a nicely formatted table with:

• User who created the entry
• Task title
• Project (column auto-hides when no entries have a project)
• Start time
• End time (or "In progress" for active timers)
• Duration
• Summary with total entries, completed entries, and total time tracked

Examples

# Start tracking a task
$ track start "Writing documentation"
Started tracking "Writing documentation"

# Start tracking with a project
$ track start "Fix login bug" -p frontend
Started tracking "Fix login bug" [frontend]

# Check the status
$ track status
Tracking: [frontend] "Fix login bug" - 1m 23s

# Try to start another task (will fail)
$ track start "Another task"
A timer is already running (Fix login bug)

# Stop the current timer
$ track stop
Stopped tracking "Fix login bug" - 5m 47s

# Resume the last timer
$ track resume
Started tracking "Fix login bug" [frontend]

# Start tracking without a title
$ track start
Started tracking

# Check status
$ track status
Tracking: 15s

# Stop tracking
$ track stop
Stopped tracking - 30s

# List all entries for today (default)
$ track list
User | Title                 | Project  | Start               | End                 | Duration
----------------------------------------------------------------------------------------------
stas | Writing documentation |          | 2026-02-03 14:00:00 | 2026-02-03 14:05:47 | 5m 47s
stas | Fix login bug         | frontend | 2026-02-03 14:10:00 | 2026-02-03 14:15:47 | 5m 47s
stas | Another task          |          | 2026-02-03 14:20:00 | In progress         | 2m 15s
----------------------------------------------------------------------------------------------
Total: 3 entries, 2 completed, 11m 34s tracked

# List entries filtered by project
$ track list --all --project frontend

# List all entries for this week
$ track list --week

# Use watch mode with interactive controls
$ track start "Writing code" -p backend --watch
⏱  Tracking: [backend] "Writing code" - 1m 23s  [s] stop  [q] quit

# Press 's' to stop the timer without leaving watch mode
⏸  Nothing is being tracked  [r] resume  [q] quit

# Press 'r' to resume, 'q' or Ctrl+C to exit

Data Storage

Tracking data is stored in a timetrack.csv file in the current working directory where you run the commands. The CSV format is:

user,title,project,start,end
stas,"Writing documentation",,2026-02-03T14:00:00.000Z,2026-02-03T14:05:47.000Z
stas,"Fix login bug",frontend,2026-02-03T14:10:00.000Z,2026-02-03T14:15:47.000Z

This makes it easy to import the data into spreadsheets or other tools for analysis. Also allows time-tracking specific projects much easier.

Old CSV files without the project column are automatically supported -- entries will be read with an empty project.

License

MIT