Time Tracker

Time Tracker

Track work time per project using local JSONL files with start/stop commands.

Requirements

• File system access for ~/.time-tracker/
• No external services or API keys needed

Instructions

Commands

Data storage

• Entries: ~/.time-tracker/entries.jsonl (one JSON per line)

  {"id": "uuid", "project": "webapp", "task": "frontend", "start": "2025-01-15T09:00:00+09:00", "end": "2025-01-15T11:30:00+09:00", "minutes": 150}
  

• Current timer: ~/.time-tracker/current.json

  {"project": "webapp", "task": "frontend", "start": "2025-01-15T09:00:00+09:00"}
  

Report format

## ⏱️ Time Report — Week of 2025-01-13

| Project | Task | Hours | Sessions |
|---------|------|-------|----------|
| webapp | frontend | 8.5h | 4 |
| webapp | backend | 3.0h | 2 |
| blog | writing | 2.5h | 3 |
| **Total** | | **14.0h** | **9** |

### Daily Breakdown
- Mon: 4.5h | Tue: 3.0h | Wed: 2.5h | Thu: 4.0h | Fri: 0h

Implementation

Create ~/.time-tracker/ directory if it doesn't exist. Use date -Iseconds for timestamps. Calculate minutes as (end - start) / 60. Append entries to JSONL file for easy parsing with jq or Python.

Edge Cases

• Forgot to stop: If current.json exists on next start, warn and ask: stop previous (auto-calculate) or discard?
• Midnight crossing: A timer started at 23:00 and stopped at 01:00 = 2 hours, not negative.
• Timezone changes: Store all times with timezone offset (ISO 8601). Convert for display.
• Empty report period: Show "No entries" rather than an empty table.
• Concurrent timers: Only one timer at a time. Stop the current one before starting a new one.

Security

• Time data is stored locally — no external transmission.
• Project/task names may reveal client work — keep ~/.time-tracker/ private.