Time Tracking Csv

The /time-tracking.track-time command uses a custom tool that automatically:

• Captures the calling agent from context.agent
• Reads the model from opencode.json configuration
• Validates and applies defaults from opencode-project.json
• Writes the entry to the CSV file

This ensures model and agent fields are always populated correctly.

Smart Duration

When no duration is provided, the tool uses smart duration calculation:

• end_time = current time (with seconds)
• start_time = end_time of the last entry today (with seconds)
• duration = difference between start and end time

This allows seamless continuation from the previous entry. If no entry exists today, it falls back to 15m duration.

Parameter Order

[issue_key] [description] [duration] [start_time] [account_key]

Examples:

/time-tracking.track-time
/time-tracking.track-time SOSO-286
/time-tracking.track-time SOSO-286 "Feature done"
/time-tracking.track-time SOSO-286 "Feature done" 1h
/time-tracking.track-time SOSO-286 "Feature done" 1h 09:30

Configuration

Environment Variable

The user email is read from the environment variable OPENCODE_USER_EMAIL:

# .env file in project root
[email protected]

If OPENCODE_USER_EMAIL is not set → Inform user: "Please create .env file with OPENCODE_USER_EMAIL=..."

Project Configuration

Configuration is read from .opencode/opencode-project.json:

{
  "time_tracking": {
    "csv_file": ".opencode/time_tracking/time-tracking.csv",
    "default_account_key": "ACCOUNT_KEY",
    "charts_dir": ".opencode/time_tracking/charts/"
  }
}

If configuration is missing → Inform user: "Please run /time-tracking.init"

Booking Configuration

Settings for booking proposals and rounding:

{
  "time_tracking": {
    "booking": {
      "rounding_minutes": 5,
      "lunch_break": {
        "start": "12:00",
        "end": "13:00"
      }
    }
  }
}

Used by:

• /time-tracking.booking-proposal - Generates booking CSV files
• /time-tracking.timesheet - Displays booking suggestions

Sync Configuration

Settings for syncing booking proposals to external systems:

{
  "time_tracking": {
    "sync": {
      "calendar": {
        "calendar_id": "[email protected]",
        "color_id": "9"
      },
      "sheets": {
        "folder_id": "your-drive-folder-id"
      }
    }
  }
}

Used by:

• /time-tracking.sync-calendar - Creates calendar events (future)
• /time-tracking.sync-sheets - Creates Google Sheets (future)

Agent Default Configuration

Agent-specific default tickets for time tracking when no ticket is found in context.

Fallback Hierarchy

The MCP plugin opencode-time-tracking uses the following fallback hierarchy:

1. Context Ticket    → From current OpenCode event (Story, Task, etc.)
       ↓ if not found
2. Agent Default     → agent_defaults["@developer"] etc.
       ↓ if agent not configured
3. Global Default    → global_default
       ↓ if not configured
4. Error             → "No ticket found"

Configuration Schema

{
  "time_tracking": {
    "agent_defaults": {
      "@developer": {
        "issue_key": "PROJ-101",
        "account_key": "TD_DEVELOPMENT"
      },
      "@reviewer": {
        "issue_key": "PROJ-102"
      },
      "@tester": {
        "issue_key": "PROJ-103"
      },
      "@coordinator": {
        "issue_key": "PROJ-104"
      }
    },
    "global_default": {
      "issue_key": "PROJ-100",
      "account_key": "TD_GENERAL"
    },
    "ignored_agents": ["@time-tracking", "@internal"]
  }
}

Field Reference

Account Key Resolution

1. agent_defaults[agent].account_key   (if present)
       ↓ if not set
2. global_default.account_key          (if present)
       ↓ if not set
3. time_tracking.default_account_key   (required fallback)

Use Cases

Excluding Agents from Automatic Tracking

Use ignored_agents to exclude specific agents from automatic time tracking via the techdivision/opencode-time-tracking plugin.

{
  "time_tracking": {
    "ignored_agents": ["@time-tracking", "@internal", "@test"]
  }
}

Common exclusions:

• @time-tracking - The time tracking agent itself (avoids recursive tracking)
• @internal - Internal utility agents
• @test - Test/debug agents

Note: This only affects automatic tracking. Manual entries via /time-tracking.track-time are not affected.

CSV Schema: time-tracking.csv

Header

id,start_date,end_date,user,ticket_name,issue_key,account_key,start_time,end_time,duration_seconds,tokens_used,tokens_remaining,story_points,description,notes,model,agent

Fields

Example Entry

"1e74792a-b460-4b55-a2e6-36c0ad8d062b","2025-01-05","2025-01-05","[email protected]","Bug SOSO-178: Fix ESLint","SOSO-178","TD_KS_1100_SYSTEM","15:58:00","17:32:00","5640","92988","107012","","Fixed ESLint blocking","CI fixes completed","anthropic/claude-opus-4","build"

CSV Parsing

Important: All Fields Are Quoted

The CSV file has all fields in quotes. These must be considered when parsing:

"uuid","2026-01-09","2026-01-09","[email protected]","","PROJ-110",...

Bash: Filter by Date

# WRONG - finds nothing because quotes are missing
awk -F',' '$2=="2026-01-09"' .opencode/time_tracking/time-tracking.csv

# CORRECT - with quotes in comparison
awk -F',' '$2=="\"2026-01-09\""' .opencode/time_tracking/time-tracking.csv

# BETTER - remove quotes then filter
awk -F',' '{gsub(/"/, ""); if ($2=="2026-01-09") print}' .opencode/time_tracking/time-tracking.csv

Bash: Extract Fields

# Remove quotes when extracting
awk -F',' '{
  gsub(/"/, "", $2);   # start_date
  gsub(/"/, "", $8);   # start_time
  gsub(/"/, "", $9);   # end_time
  gsub(/"/, "", $10);  # duration_seconds
  gsub(/"/, "", $11);  # tokens_used
  gsub(/"/, "", $6);   # issue_key
  gsub(/"/, "", $14);  # description
  gsub(/"/, "", $16);  # model
  print $2, $8, $9, $10, $11, $6, $14, $16
}' .opencode/time_tracking/time-tracking.csv

Recommended Parsing Pattern

# Complete: Filter + extract fields + remove quotes
awk -F',' '
  NR > 1 {  # Skip header
    # Remove quotes from all relevant fields
    for (i=1; i<=NF; i++) gsub(/"/, "", $i)
    
    # Filter by date
    if ($2 == "2026-01-09") {
      print $8, $9, $10, $11, $6, $14, $16
    }
  }
' .opencode/time_tracking/time-tracking.csv

CSV Schema: worklogs-sync.csv

For /time-tracking.sync-worklogs - combines Time-Tracking + Calendar:

date,start_time,duration_hours,issue_key,account_key,calendar_event_id,description,source,sync_status

Rounding Rules

Time Rounding (5-Minute Precision)

Round to nearest 5-minute mark:

Formula:

rounded_minutes = round(minutes / 5) * 5

Duration Rounding (5-Minute Precision)

Round seconds to nearest 5-minute unit:

Formula:

rounded_minutes = round(seconds / 60 / 5) * 5
duration_hours = rounded_minutes / 60

Sequential Consolidation (Basic)

For raw display, directly consecutive entries with the same issue_key are merged:

Rules:

1. Only if entries directly follow each other (no others in between)
2. Only if issue_key is not empty and identical
3. description: Combined with " + "

Note: For extended cumulation with gap tolerance and value-oriented descriptions, see skill time-tracking-booking.

CSV Generation in Bash

Escaping Function

escape_csv() {
  echo "$1" | sed 's/"/""/g'
}

Format CSV Line

uuid=$(uuidgen | tr '[:upper:]' '[:lower:]')
description=$(escape_csv "Fixed \"critical\" bug")
notes=$(escape_csv "All tests passing")

# ALL fields in quotes (17 fields including model and agent)
csv_line="\"${uuid}\",\"${start_date}\",\"${end_date}\",\"${user}\",\"${ticket_name}\",\"${issue_key}\",\"${account_key}\",\"${start_time}\",\"${end_time}\",\"${duration_seconds}\",\"${tokens_used}\",\"${tokens_remaining}\",\"${story_points}\",\"${description}\",\"${notes}\",\"${model}\",\"${agent}\""

echo "$csv_line" >> "$csv_file"

Important Rules

• All fields in double quotes ""
• Escape quotes in values: " → ""
• Empty fields as "" (not empty commas)
• Integer fields also in quotes

Duration Calculation

Seconds to Hours (Rounded)

# Seconds → rounded hours
duration_seconds=5640
rounded_minutes=$(( (duration_seconds + 150) / 300 * 5 ))  # +150 for rounding
duration_hours=$(echo "scale=4; $rounded_minutes / 60" | bc)
# 5640 sec → 95 min → 1.5833h

Sessions Over Midnight

When start_date ≠ end_date: