time-reports

name	time-reports
description	Generate time tracking reports from terminal-time-tracker data. Use when summarizing hours by project, comparing weeks, analyzing daily patterns, or exporting time data for invoicing. Triggers include "time report", "hours by project", "weekly summary", "time breakdown", "how long did I spend", "invoice export".

time-reports

Guide to generating and interpreting time reports with terminal-time-tracker.

Report Types

Daily Report (default)

ttm report

Shows all projects with time logged today. Running timers are included with a + indicator.

Weekly Report

ttm report --week

Current week Monday through Sunday. All projects with totals.

Monthly Report

ttm report --month

Current calendar month totals.

Custom Date Range

ttm report --from 2026-03-01 --to 2026-03-20
ttm report --from 2026-03-01              # from date to today

Per-Project Breakdown

ttm report --project myproject
ttm report --week --project myproject    # daily breakdown this week
ttm report --month --project myproject  # daily breakdown this month

Shows day-by-day entries for the project instead of project totals.

Reading the Report Table

  PROJECT            DURATION     ENTRIES   PERCENT
  myproject          18h 45m      12         61%
  docs               6h 30m       8          21%
  infra              3h 00m       3           9%
  meetings           2h 45m       5           9%

  total: 31h 00m  |  28 entries  |  4 projects

• DURATION: total time for all entries in range
• ENTRIES: number of individual log entries
• PERCENT: share of total time for the period
• Running timers show + after duration and * before percent

Exporting for Invoicing

# Export all entries for a month as CSV
ttm export --from 2026-03-01 --to 2026-03-31 --output march.csv

# Export as JSON for processing
ttm export --from 2026-03-01 --to 2026-03-31 --format json --output march.json

# Filter by project for a client
ttm export --project clientproject --from 2026-03-01 --to 2026-03-31

CSV columns: id, project, note, started_at, stopped_at, duration_seconds

Bar Chart Summary

ttm stats --week

Shows ASCII bar chart with hours per day for the current week. Useful for spotting patterns in daily work habits.

Common Queries

# How long did I work today?
ttm report

# How long did I work this week?
ttm report --week

# How much time on a specific project this month?
ttm report --month --project myproject

# Top projects all-time
ttm stats

# What did I work on yesterday?
ttm list --from yesterday --to yesterday

Interpreting Percentages

Percentages in the report are computed as (project duration / total duration * 100) rounded to the nearest whole number. They sum to 100% within rounding. Running timers are included using their current elapsed time as a snapshot.