track-task-time

A tool to track the time of tasks. The ttt CLI provides explicit start/stop and pause/resume commands, stores data locally in JSON, and reports daily totals.

Disclaimer

I use this project as a playground to get familiar with how to use agentic AI capabilities to delegate programming tasks. Most to all of the code is generated by AI.

ttt CLI

ttt is a small, cross-platform CLI for tracking task time with explicit start/stop and pause/resume commands.

Features

• Start/stop a single active task at a time.
• Pause/resume without splitting into multiple tasks.
• Daily report showing each task with start/end times, most recent first.
• Encrypted local storage with a passphrase.

Usage

ttt [--data-file <path>] <command>

Command Reference

• start [task]: Start tracking a task. Prompts for a name if omitted.
• stop: Stop the active or paused task.
• pause: Pause the active task.
• resume: Resume the paused task.
• status: Show the current task and elapsed time.
• location: Show the data file location.
• list [--today|--week]: List tasks and totals with optional date filters.
• edit [flags]: Edit a task name or time segments (interactive list by default).
• report [--today]: Show today's entries with start/end times (default: today).
• rekey: Change the passphrase for the data file.
• restore: Restore the data file from a backup.
• version: Show the CLI version.

Quick Start

ttt start "Write docs"
ttt start
ttt pause
ttt resume
ttt status
ttt report
ttt stop
ttt rekey
ttt restore
ttt version

Listing Tasks

• All tasks: ttt list
• Only today: ttt list --today
• This week: ttt list --week
• Output includes index, status, name, id, and total duration.

Editing Tasks

• Interactive edit: ttt edit (select from list, then edit name/times).
• Rename by id: ttt edit --id <TASK_ID> --name "New name".
• Edit by index: ttt edit --index 2 --name "New name".
• Adjust task timestamps: ttt edit --id <TASK_ID> --created-at 2026-01-03T12:00:00Z --closed-at open.
• Adjust a segment time: ttt edit --id <TASK_ID> --segment-edit 1,2026-01-03T12:00:00Z,open (END can be open).
• --segment-edit can be repeated for multiple segments.

Data File

• Default location: OS-specific user data directory, e.g. ~/.local/share/ttt/ttt.json on Linux.
• Override with --data-file /path/to/ttt.json.
• File contents are encrypted with a passphrase.
• The CLI prompts for the passphrase on each run.
• Change the passphrase with ttt rekey.
• Automatic backups are created on each write (.bak1 to .bak3).
• Restore a backup with ttt restore.

Output Format

• Durations are printed as HH:MM:SS.
• Report output starts with the date, then lines like 09:00:00 - 10:12:05 - Task Name (01:12:05), followed by a total line.
• List output ends with a total line for the selected window.

Development Setup

Build the CLI

cargo build

Run tests

cargo test

Unit tests cover formatting and aggregation logic.

Pre-commit Hooks

First-time setup for the virtual environment:

python3 -m venv .venv

Install pre-commit and enable the hooks:

. .venv/bin/activate
pip install pre-commit
pre-commit install

Run all hooks manually:

. .venv/bin/activate
pre-commit run --all-files

Release Process

1. Update app/Cargo.toml version and add entries to CHANGELOG.md.
2. Commit the changes to main.
3. Create and push a tag:

git tag vX.Y.Z
git push origin vX.Y.Z

Pushing the tag triggers the GitHub Actions release workflow to build binaries and publish release notes from the changelog.

Building the container image

docker build . -t track-task-time:0.1.3

Running and attaching to the container image

docker container run -d -it --rm --mount type=bind,src=./,dst=/app track-task-time:0.1.4 bash
docker attach <CONTAINER_ID/NAME>

Authenticating with Codex

codex login --device-auth