Initial Setup

Header Information: At the top of each page, include:

• Date (month/year)
• Page number
• "Prepared by" (your initials)
• "Time Tracking Log" title

Column Headers: Create the following columns:

For billing purposes, you may want to add additional columns:

• Rate (hourly rate for the project)
• Amount (duration × rate)
• Invoice # (when the time is billed)

1. Time Distribution: Calculate total hours by category
2. Billable Ratio: Determine percentage of billable vs. non-billable time
3. Project Allocation: Assess time spent on each client/project
4. Productivity Patterns: Identify your most productive times of day
5. Balance Assessment: Evaluate personal vs. professional time allocation

Create a CSV file with the following columns:

date,start_time,end_time,duration,project,category,description,billable,rate,amount
2025-06-10,09:15,10:45,1.5,"ABC Corp","Development","API integration for payment system",true,125,187.5
2025-06-10,10:50,11:30,0.67,"Internal","Admin","Email and scheduling",false,0,0
2025-06-10,13:00,14:45,1.75,"Personal","Health","Gym and lunch",false,0,0
2025-06-10,15:00,17:30,2.5,"XYZ Inc","Design","Wireframes for mobile app",true,125,312.5
2025-06-11,08:30,10:00,1.5,"Internal","Learning","React hooks tutorial",false,0,0
      

This format provides several advantages:

• Duration Calculation: Formulas can automatically calculate time spent
• Sorting and Filtering: Easily view time by project, category, or date
• Visualization: Create charts and graphs of time allocation
• Reporting: Generate client billing reports automatically
• Portability: CSV files can be used across multiple platforms and applications

1. Create the Basic Structure: Set up columns matching the CSV format above
2. Format Date and Time Columns: Use appropriate date and time formats
3. Add Duration Formula: Calculate the time difference between start and end times

   =(HOUR(B2-A2)*60+MINUTE(B2-A2))/60

4. Add Amount Formula: Multiply duration by rate for billable entries

   =IF(G2="true",E2*F2,0)

5. Create Data Validation Lists: For projects and categories to ensure consistency
6. Add Summary Formulas: Create totals and subtotals by category and project

Here's a basic Python script that provides a command-line interface for logging time entries to your CSV file:

#!/usr/bin/env python3
"""
TimeTrack: A simple command-line time tracking tool
Usage:
  - Start an activity: timetrack start "Project Name" "Category" "Description"
  - End current activity: timetrack stop
  - List today's activities: timetrack list
  - Report on time: timetrack report [--from=DATE] [--to=DATE] [--project=NAME] [--category=NAME]
"""

import argparse
import csv
import datetime
import os
import sys
from pathlib import Path

# Configuration
DATA_DIR = Path.home() / ".timetrack"
DATA_FILE = DATA_DIR / "time_entries.csv"
CURRENT_FILE = DATA_DIR / "current_activity.txt"

# Column headers for the CSV file
HEADERS = ["date", "start_time", "end_time", "duration", "project", "category", 
           "description", "billable", "rate", "amount"]

# Ensure data directory exists
DATA_DIR.mkdir(exist_ok=True)

# Create the CSV file if it doesn't exist
if not DATA_FILE.exists():
    with open(DATA_FILE, 'w', newline='') as f:
        writer = csv.writer(f)
        writer.writerow(HEADERS)

def start_activity(args):
    """Start a new activity and record it."""
    now = datetime.datetime.now()
    date = now.strftime("%Y-%m-%d")
    time = now.strftime("%H:%M")
    
    # Check if there's already an activity in progress
    if CURRENT_FILE.exists():
        with open(CURRENT_FILE, 'r') as f:
            current = f.read().strip().split(',')
        
        print(f"Error: Activity '{current[4]}' already in progress since {current[1]}.")
        print("Stop it first with 'timetrack stop'")
        return
    
    # Record the current activity
    billable = "true" if args.billable else "false"
    rate = args.rate if args.rate else "0"
    
    activity = [date, time, "", "", args.project, args.category, 
                args.description, billable, rate, ""]
    
    with open(CURRENT_FILE, 'w') as f:
        f.write(','.join([str(x) for x in activity]))
    
    print(f"Started: {args.project} - {args.description} at {time}")

def stop_activity(args):
    """Stop the current activity and calculate duration."""
    if not CURRENT_FILE.exists():
        print("No activity currently in progress.")
        return
    
    now = datetime.datetime.now()
    end_time = now.strftime("%H:%M")
    
    # Read the current activity
    with open(CURRENT_FILE, 'r') as f:
        activity = f.read().strip().split(',')
    
    # Calculate duration
    start_dt = datetime.datetime.strptime(f"{activity[0]} {activity[1]}", "%Y-%m-%d %H:%M")
    end_dt = datetime.datetime.strptime(f"{activity[0]} {end_time}", "%Y-%m-%d %H:%M")
    
    duration_hours = (end_dt - start_dt).total_seconds() / 3600
    duration = round(duration_hours, 2)
    
    # Calculate amount for billable activities
    amount = 0
    if activity[7] == "true" and activity[8] != "":
        amount = float(activity[8]) * duration
    
    # Update the activity with end time and duration
    activity[2] = end_time
    activity[3] = str(duration)
    activity[9] = str(amount)
    
    # Add to CSV file
    with open(DATA_FILE, 'a', newline='') as f:
        writer = csv.writer(f)
        writer.writerow(activity)
    
    # Delete current activity file
    CURRENT_FILE.unlink()
    
    print(f"Stopped: {activity[4]} - {activity[6]}")
    print(f"Duration: {duration} hours" + (f" (${amount:.2f})" if amount > 0 else ""))

def list_activities(args):
    """List activities for today or a specified date."""
    target_date = args.date if args.date else datetime.datetime.now().strftime("%Y-%m-%d")
    
    if not DATA_FILE.exists():
        print("No activities recorded yet.")
        return
    
    total_duration = 0
    total_billable = 0
    total_amount = 0
    activities_found = False
    
    print(f"\nActivities for {target_date}:\n")
    print(f"{'Time':<12}{'Duration':<10}{'Project':<15}{'Category':<15}{'Description':<30}{'Amount':<10}")
    print("-" * 90)
    
    with open(DATA_FILE, 'r', newline='') as f:
        reader = csv.reader(f)
        next(reader)  # Skip header
        
        for row in reader:
            if row[0] == target_date:
                activities_found = True
                start = row[1]
                end = row[2]
                duration = float(row[3])
                project = row[4]
                category = row[5]
                description = row[6]
                billable = row[7] == "true"
                amount = float(row[9]) if row[9] else 0
                
                time_range = f"{start}-{end}"
                amount_str = f"${amount:.2f}" if billable else ""
                
                print(f"{time_range:<12}{duration:<10.2f}{project:<15}{category:<15}{description:<30}{amount_str:<10}")
                
                total_duration += duration
                if billable:
                    total_billable += duration
                    total_amount += amount
    
    if activities_found:
        print("-" * 90)
        print(f"Total: {total_duration:.2f} hours ({total_billable:.2f} billable, ${total_amount:.2f})")
    else:
        print(f"No activities found for {target_date}")
    
    # Show current activity if any
    if CURRENT_FILE.exists():
        with open(CURRENT_FILE, 'r') as f:
            current = f.read().strip().split(',')
        
        if current[0] == target_date:
            print("\nCurrent activity:")
            print(f"Started at {current[1]}: {current[4]} - {current[6]}")

def generate_report(args):
    """Generate a report of activities based on filters."""
    if not DATA_FILE.exists():
        print("No activities recorded yet.")
        return
    
    # Default to last 7 days if no date range specified
    today = datetime.datetime.now().date()
    from_date = args.from_date if args.from_date else (today - datetime.timedelta(days=7)).strftime("%Y-%m-%d")
    to_date = args.to_date if args.to_date else today.strftime("%Y-%m-%d")
    
    # Filter options
    project_filter = args.project
    category_filter = args.category
    
    # Collect data for reporting
    entries = []
    with open(DATA_FILE, 'r', newline='') as f:
        reader = csv.DictReader(f)
        for row in reader:
            entry_date = row['date']
            if from_date <= entry_date <= to_date:
                if project_filter and row['project'] != project_filter:
                    continue
                if category_filter and row['category'] != category_filter:
                    continue
                entries.append(row)
    
    if not entries:
        print(f"No matching activities found from {from_date} to {to_date}.")
        return
    
    # Calculate totals
    total_duration = sum(float(entry['duration']) for entry in entries)
    total_billable = sum(float(entry['duration']) for entry in entries if entry['billable'] == 'true')
    total_amount = sum(float(entry['amount']) for entry in entries if entry['amount'])
    
    # Generate summary by project
    projects = {}
    for entry in entries:
        project = entry['project']
        if project not in projects:
            projects[project] = {
                'duration': 0,
                'billable': 0,
                'amount': 0
            }
        
        duration = float(entry['duration'])
        projects[project]['duration'] += duration
        
        if entry['billable'] == 'true':
            projects[project]['billable'] += duration
            projects[project]['amount'] += float(entry['amount']) if entry['amount'] else 0
    
    # Generate summary by category
    categories = {}
    for entry in entries:
        category = entry['category']
        if category not in categories:
            categories[category] = {
                'duration': 0,
                'billable': 0,
                'amount': 0
            }
        
        duration = float(entry['duration'])
        categories[category]['duration'] += duration
        
        if entry['billable'] == 'true':
            categories[category]['billable'] += duration
            categories[category]['amount'] += float(entry['amount']) if entry['amount'] else 0
    
    # Print report
    print(f"\nTime Report: {from_date} to {to_date}")
    print(f"Total Hours: {total_duration:.2f} ({total_billable:.2f} billable, ${total_amount:.2f})")
    
    print("\nBreakdown by Project:")
    print(f"{'Project':<20}{'Hours':<10}{'Billable':<10}{'Amount':<10}")
    print("-" * 50)
    for project, data in sorted(projects.items(), key=lambda x: x[1]['duration'], reverse=True):
        print(f"{project:<20}{data['duration']:<10.2f}{data['billable']:<10.2f}${data['amount']:<9.2f}")
    
    print("\nBreakdown by Category:")
    print(f"{'Category':<20}{'Hours':<10}{'Billable':<10}{'Amount':<10}")
    print("-" * 50)
    for category, data in sorted(categories.items(), key=lambda x: x[1]['duration'], reverse=True):
        print(f"{category:<20}{data['duration']:<10.2f}{data['billable']:<10.2f}${data['amount']:<9.2f}")

def main():
    parser = argparse.ArgumentParser(description="Simple command-line time tracking")
    subparsers = parser.add_subparsers(dest="command", help="Command to run")
    
    # Start command
    start_parser = subparsers.add_parser("start", help="Start a new activity")
    start_parser.add_argument("project", help="Project or client name")
    start_parser.add_argument("category", help="Category of activity")
    start_parser.add_argument("description", help="Description of activity")
    start_parser.add_argument("--billable", action="store_true", help="Mark as billable")
    start_parser.add_argument("--rate", type=float, help="Hourly rate (for billable activities)")
    
    # Stop command
    stop_parser = subparsers.add_parser("stop", help="Stop the current activity")
    
    # List command
    list_parser = subparsers.add_parser("list", help="List activities for today")
    list_parser.add_argument("--date", help="Date to list (YYYY-MM-DD)")
    
    # Report command
    report_parser = subparsers.add_parser("report", help="Generate time report")
    report_parser.add_argument("--from-date", help="Start date (YYYY-MM-DD)")
    report_parser.add_argument("--to-date", help="End date (YYYY-MM-DD)")
    report_parser.add_argument("--project", help="Filter by project")
    report_parser.add_argument("--category", help="Filter by category")
    
    args = parser.parse_args()
    
    if args.command == "start":
        start_activity(args)
    elif args.command == "stop":
        stop_activity(args)
    elif args.command == "list":
        list_activities(args)
    elif args.command == "report":
        generate_report(args)
    else:
        parser.print_help()

if __name__ == "__main__":
    main()
      

How to Use the Script

Save this script as timetrack.py, make it executable (chmod +x timetrack.py), and move it to a directory in your PATH. Then you can use it as follows:

The script stores data in ~/.timetrack/time_entries.csv, which you can easily import into a spreadsheet for additional analysis if needed.