Timer

⚠️ BETA — GitScrum CLI is in active development. Open source under the MIT license. Available on GitHub. Built for developers — Tasks, timers, sprints, and analytics in your terminal. Git-aware. CI/CD ready.

Time tracking that stays out of your way. Start timers, log hours, generate reports — all from your terminal.

Commands

Check Active Timer

gitscrum timer

Active: GS-1234 | Running: 2h 15m
Started: 09:00

Or if no timer is running:

No active timer.

Start Timer

gitscrum timer start GS-1234

Timer started for GS-1234 at 09:15

Git-Aware Start

If you're on a branch like feature/GS-1234-oauth, you can start without specifying the task:

gitscrum timer start

Timer started for GS-1234 at 09:15

With Description

gitscrum timer start GS-1234 -d "Implementing OAuth device flow"

Stop Timer

gitscrum timer stop

Logged 3h 45m to GS-1234
Total today: 7h 15m

Log Time Manually

Forgot to start the timer? No problem.

gitscrum timer log GS-1234 2h30m

Logged 2h 30m to GS-1234

With Description

gitscrum timer log GS-1234 45m -d "Code review for PR #42"

Logged 45m to GS-1234: Code review for PR #42

For a Previous Day

gitscrum timer log GS-1234 4h --date 2026-02-06

Logged 4h to GS-1234 on Feb 6, 2026

Duration Format

Multiple formats are supported:

Time Reports

Today's Work

gitscrum timer report --day

Today (Feb 7, 2026) — 7h 15m

TASK      DURATION  DESCRIPTION
GS-1234   3h 45m    Implement OAuth flow
GS-1234   2h 30m    Testing and debugging
GS-1198   1h 00m    Fix pagination bug

This Week

gitscrum timer report --week

This Week — 32h 15m

PROJECT       HOURS    TASKS
backend-api   18h 30m  GS-1234, GS-1198, GS-1156
web-app       10h 45m  GS-1089, GS-1091
docs           3h 00m  GS-1045

Most time: GS-1234 (12h 30m)

This Month

gitscrum timer report --month

By Project

gitscrum timer report --week -p backend-api

Team Report

gitscrum timer report --week --team

Team Time Report — This Week

USER      HOURS    TOP PROJECT
alice     38h 15m  backend-api
bob       35h 30m  web-app
charlie   29h 45m  mobile-app

Total: 103h 30m

JSON Output

gitscrum timer report --week --json

Perfect for exporting to spreadsheets or invoicing tools.

Configuration

In .gitscrum.yml:

timer:
  # Auto-start timer when switching to task branch
  auto_start: true
  
  # Auto-stop timer when switching away
  auto_stop: true
  
  # Round to nearest 15 minutes
  round_to: 15
  
  # Minimum 5 minutes to log
  min_duration: 5
  
  # Remind after 2 hours of inactivity
  reminder_after: 120

Rounding

When round_to: 15:

• 7 minutes → 15 minutes
• 23 minutes → 30 minutes
• 38 minutes → 45 minutes

Minimum Duration

When min_duration: 5, entries under 5 minutes are ignored. Prevents accidental micro-entries from cluttering your timesheet.

Daily Workflow

# Morning: What did I log yesterday?
$ gitscrum timer report --day

# Start working
$ gitscrum timer start GS-1234

# Check status mid-day
$ gitscrum timer
Active: GS-1234 | Running: 2h 15m

# Lunch break? Stop and restart
$ gitscrum timer stop
$ gitscrum timer start GS-1234

# End of day: Stop and review
$ gitscrum timer stop
$ gitscrum timer report --day

Tips

Git-Aware

If you don't specify a task code, the CLI automatically detects it from your current branch:

$ git checkout feature/GS-1234-oauth
$ gitscrum timer start
Timer started for GS-1234 at 09:00

Auto-Start on Branch Switch

Enable in .gitscrum.yml:

timer:
  auto_start: true

Now, every time you checkout a task branch, the timer starts automatically.

Forgot to Start?

Log time after the fact:

gitscrum timer log GS-1234 3h -d "Debugging OAuth flow"

Billable Hours Export

# Export week's time as CSV
gitscrum timer report --week --json | jq -r '.entries[] | [.date, .task, .duration, .description] | @csv' > timesheet.csv

CI/CD Integration

Track deployment time:

# GitHub Actions
- name: Track deployment
  run: |
    START=$(date +%s)
    # ... deployment steps ...
    END=$(date +%s)
    DURATION=$((END - START))
    MINUTES=$((DURATION / 60))
    gitscrum timer log $TASK "${MINUTES}m" -d "Deployment to production"