tasktimer

Task Timer (tt) is a dead simple TUI task timer.

---

• Install
• Usage
  • Projects
  • Keyboard shortcuts
  • Start, pause, and stop from the CLI
  • Report
  • Edit
  • List projects
  • Backup and restore
• FAQ

Install

homebrew:

brew install caarlos0/tap/tt

apt:

echo 'deb [trusted=yes] https://repo.caarlos0.dev/apt/ /' | sudo tee /etc/apt/sources.list.d/caarlos0.list
sudo apt update
sudo apt install tt

yum:

echo '[caarlos0]
name=caarlos0
baseurl=https://repo.caarlos0.dev/yum/
enabled=1
gpgcheck=0' | sudo tee /etc/yum.repos.d/caarlos0.repo
sudo yum install tt

arch linux:

yay -S tasktimer-bin

deb/rpm/apk:

Download the .apk, .deb or .rpm from the releases page and install with the appropriate commands.

manually:

Download the pre-compiled binary for your platform from the releases page and place it somewhere on your $PATH.

To build from source, see CONTRIBUTING.md.

Usage

To get started, just run tt:

tt

You'll be presented with something like this:

Type a description of what you're working on and press Enter to start timing.

Press Enter again (with an empty input) to stop the current timer, or type a new task description and press Enter to stop the previous task and immediately start the new one.

Each task has its own timer. The total time across all tasks is shown in the header:

Projects

By default, all tasks are saved under a project named default. Use the -p flag to work with a named project:

tt -p myproject

This flag is supported by all subcommands.

Keyboard shortcuts

Key	Action
Enter	Start a new task / stop the current timer
r	Restart the selected task (copies its name into the input)
p	Pause or resume the current task
d	Delete the selected task
ESC	Stop the current task and blur the input field
↑ / ↓	Navigate the task list (when input is not focused)
Page Up / Page Down	Scroll the task list
/	Filter the task list
Ctrl+C	Stop the current timer and exit

Start, pause, and stop from the CLI

Control timers without launching the TUI — useful in scripts, shell aliases, or CI hooks:

tt start writing tests     # stop any running task, start a new one
tt pause                   # freeze the current timer (time stops accumulating)
tt resume                  # continue the paused task from where it left off
tt stop                    # stop all running or paused tasks

These commands respect the -p flag for named projects:

tt -p myproject start "fixing the build"
tt -p myproject pause

A paused task shows [paused] in the TUI task list and its elapsed time is frozen until resumed. Press p in the TUI to toggle pause/resume on the active task.

Report

Generate a Markdown report for the current project:

tt report
# or
tt r

Output goes to STDOUT, so you can save or pipe it:

tt report > report.md
tt -p myproject report | pbcopy

Filter by date range with --since and --until (format: YYYY-MM-DD):

tt report --since 2026-05-19 --until 2026-05-23   # this week only
tt report --since 2026-05-22                       # today onwards

The total time shown in the report header reflects only the filtered tasks.

Edit

If you forgot to stop a timer, use the edit command to fix it:

tt edit
# or
tt e

The current project is exported to a temporary JSON file and opened in your $EDITOR. Save and close the file to apply the changes.

Note: $EDITOR must be set in your environment (e.g. export EDITOR=vim).

List projects

List all projects that have recorded data:

tt list

Add -v to see task counts and total time per project:

tt list -v
# default (42 tasks, 3h 15m)
# work    (18 tasks, 9h 40m)

Backup and restore

Export and import task data as JSON:

tt to-json backup.json
tt from-json backup.json

FAQ

Where are data and logs stored?

Depends on the OS. Run this to see the paths used on your machine:

tt paths

How do I get help for a specific command?

Pass --help to any command:

tt --help
tt report --help

Stargazers over time