⏱️ Time Tracker CLI (tt)

A lightweight, privacy-focused CLI tool for tracking your daily work activity. Supports live timer tracking, manual log entries, daily summaries, and Git-based syncing — all stored in simple yearly .log files.

This tool is designed for developers, creators, or anyone who wants accurate time tracking without third-party monitoring or intrusive analytics.

---

🔥 Features

✔ Live Timer Mode

Start a timer for any task and stop it when you're done. Automatically logs the entry.

✔ Manual Entry Mode

Add time blocks manually for meetings, learning, offline work, etc.

✔ Daily & Monthly Summaries

See how much time you spent per category, including totals and block counts.

✔ Git Sync

Convenient command to add → commit → push your log file.

✔ Zero Surveillance

• No automatic commit fetching.
• No analytics.
• Your data stays with you.

---

📦 Installation

From Source

1. Clone the repository:

   git clone https://github.com/danielkestrel/tt-cli.git
   cd tt-cli

2. Install via pipx (Recommended):

   pipx install .

   This avoids "externally-managed-environment" errors on modern systems.

3. Or, install in a virtual environment:

   python3 -m venv venv
   source venv/bin/activate
   pip install .

Now you can use the tt command anywhere! (If using venv, remember to source venv/bin/activate first).

Manual Usage (No Install)

If you prefer not to install it, you can run the script directly:

chmod +x timetracker.py
./timetracker.py <command>

---

🚀 Usage

LIVE TIMER

Start tracking:

tt start <category> <description>

Example:

tt start dev "working on CLI features"

Pause tracking:

tt pause

Resume tracking:

tt resume

Stop and save:

tt stop

Note: If you paused during the session, the "Start Time" in the log will be adjusted forward to reflect your actual active duration.

Cancel without saving:

tt cancel

Check status:

tt status

---

MANUAL ENTRY

Start the guided input mode:

tt log

---

ANALYSIS

Summary for today:

tt summary

Summary for any date:

tt summary 2025-02-01

Weekly summary:

tt week

Monthly summary:

tt month

---

SYNC WITH GIT

Run add → commit → push with confirmations:

tt sync

---

🗂 Log Format

Every entry is stored in a yearly file in your current directory:

2025.log

Each line uses:

YYYY-MM-DD HH:MM HH:MM category description

Examples:

2025-01-01 09:00 11:40 dev    building API endpoints
2025-01-01 12:30 13:00 meet   sprint planning

---

🧭 Common Categories

Category	Meaning
dev	coding, development work
learn	tutorials, reading, research
meet	meetings, calls
misc	general tasks
break	breaks, rest

All categories are auto-trimmed to 5 characters.

---

🛠 Development

Setup

git clone https://github.com/danielkestrel/tt-cli.git
cd tt-cli

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests.

---

🔐 Privacy Philosophy

This tracker avoids: ❌ automatic commit history scanning ❌ background sync ❌ online storage ❌ activity analytics

Your logs are plain text, offline, and fully under your control.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.