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 a tracked work session with bare track
Run normal shell commands from the tracking REPL
Stop automatically with Ctrl+C, Ctrl+D, or /quit
Set task name and project during a session with slash commands
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

Clone this repository:

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

Install dependencies:

bun install

Build the project:

bun run build

Link the CLI globally:

bun link

The track command is now available globally on your system.

Usage

Start an interactive work session

Run track with no subcommand to start timing immediately and enter the tracking REPL:

track

Optionally set an initial title or project:

track "Writing docs" --project cli
track "Fix login bug" -p frontend

Inside the REPL, lines starting with / are track commands:

/name Writing docs
/project cli
/status
/list
/help
/quit

Any other line runs in your shell. cd is handled by the REPL so later commands use the new directory:

cd src
bun test
git status

The timer is written to the timetrack.csv file in the directory where track was launched, even if you cd inside the REPL. Exit with Ctrl+C, Ctrl+D, or /quit to stop the timer.

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

FAQs

What is @heyimstas/timetracking?

Is @heyimstas/timetracking well maintained?

Package last updated on 14 Jul 2026

@heyimstas/timetracking

track

Description