tt — Time Tracker CLI

A small command-line tool for tracking your time and (optionally) syncing worklogs to Jira. When run from inside a git repo on a branch like ABC-123_short-description, entries are automatically tagged with the repo and Jira ticket.

Features

• Add, list, search, edit, and remove time entries from the terminal
• Flexible duration input (30m, 1.5h, 1h30m, raw minutes like 90)
• Auto-captures the current git repo and Jira key (from branch prefix) on add
• Optional Jira worklog sync (create / update / delete) via REST + PAT
• Summaries grouped by date, Jira ticket, repo, or week
• GitHub-style activity heatmap (tt heatmap)
• Weekly hours target with progress banner across list, summary, heatmap
• tt jira open to launch the current branch's ticket in your browser
• Rich-powered colored output; table, list, and json formats
• Local JSON storage at ~/.tt/data.json; logs at ~/.tt/tt.log

Requirements

• Python 3 (managed via pipenv; python_version = "3" in the Pipfile)
• pipenv on your PATH
• bash (for the wrapper / installer)
• A Jira Cloud account + Personal Access Token if you want worklog sync

Runtime dependencies (installed by pipenv): click, requests, rich.

Installation

Clone the repo, then run the installer:

git clone https://github.com/jitteryjuice/tt.git
cd tt
./install.sh

install.sh will:

1. Provision a pipenv-managed virtualenv and install dependencies.
2. Symlink tt.sh into ~/.local/bin/tt.

Make sure ~/.local/bin is on your PATH, then verify:

tt --help
tt --version

The tt command runs pipenv run python -m tt inside the repo's virtualenv, so you can invoke it from anywhere — git context (repo + branch) is captured from the directory you ran it from.

Manual install (no installer)

pipenv install
pipenv run python -m tt --help

Configuration

State lives under ~/.tt/:

• ~/.tt/data.json — entries
• ~/.tt/config.json — Jira URL, email, weekly target
• ~/.tt/tt.log — debug log

Jira sync requires three values. The PAT is only ever read from the environment; URL and email can be set via tt config or env vars:

Field	env var	tt config flag
URL	USER_JIRA_URL	--jira-url
email	USER_EMAIL	--email
PAT	USER_JIRA_PAT	(env only)

export USER_JIRA_PAT="…"          # required for sync, never persisted
tt config --jira-url https://your-org.atlassian.net --email you@example.com
tt config --weekly-hours 40        # optional progress banner; pass 0 to clear
tt config --show                   # show effective config + what's missing

If Jira is not configured, tt add still works locally and will tell you sync was skipped.

Usage

Add an entry

tt add --task "Code review" --duration 45m
tt add -t "Standup" -d "Daily" -l 15m
tt add                              # interactive prompts for missing fields
tt add --no-jira -t "Personal" -l 30m   # skip git/Jira capture entirely

When run inside a git repo on a branch like ABC-123_thing, the entry is tagged with the repo and Jira key, and (if configured) a worklog is posted to ABC-123. The returned worklog id is stored so tt remove / tt edit can update Jira too.

List entries

tt list                             # today
tt list --since yesterday
tt list --since "7 days ago" --to today
tt list --since 2026-04-01 --to 2026-04-30
tt list -f json                     # table | list | json

Search

Free-form match across date, task, description, repo, and Jira key:

tt search meeting
tt search "code review" -f list
tt search ABC-123

Remove an entry

Indices are 1-based, newest first.

tt remove                           # interactive picker (shows recent 20)
tt remove 3 -y                      # remove 3rd-newest, no confirmation
tt remove 3 --keep-jira             # remove locally but leave the worklog

Edit an entry

tt edit                             # interactive picker + prompts
tt edit 1 -l 1h15m
tt edit 2 -t "New task" -d "New desc" --keep-jira

Editing re-posts the Jira worklog (delete + create) unless --keep-jira.

Summary

tt summary                          # today, grouped by date
tt summary --since "7 days ago" --by jira
tt summary --by repo
tt summary --by week                # multi-week breakdown vs. weekly target

Heatmap

tt heatmap                          # last 12 weeks
tt heatmap -w 26

Open the current ticket

tt jira open                        # uses current branch's Jira prefix
tt jira open ABC-123

Duration formats

• Minutes: 30m, 45m, 90m, or a bare integer like 90
• Hours: 1h, 2.5h
• Combined: 1h30m, 2h15m

Date expressions

Accepted by --since and --to:

• today, yesterday
• N days ago (e.g. 7 days ago)
• YYYY-MM-DD

Data location override

Commands that touch storage accept --data-file PATH to use an alternate JSON file (handy for tests or per-project trackers):

tt list --data-file ./scratch.json

License

MIT — see LICENSE.