@techdivision/opencode-time-tracking

Automatic time tracking plugin for OpenCode. Tracks session duration and tool usage, writing entries to a CSV file compatible with Jira worklog sync.

Installation

Add to your opencode.json:

{
  "plugin": ["@techdivision/opencode-time-tracking"]
}

Configuration

1. Project Configuration

Add the time_tracking section to your .opencode/opencode-project.json:

{
  "$schema": "https://raw.githubusercontent.com/techdivision/opencode-plugins/main/schemas/opencode-project.json",
  "time_tracking": {
    "csv_file": "~/time_tracking/time-tracking.csv",
    "global_default": {
      "issue_key": "PROJ-MISC",
      "account_key": "YOUR_ACCOUNT_KEY"
    }
  }
}

2. User Email (Environment Variable)

Set your user email via the OPENCODE_USER_EMAIL environment variable.

Add to your .env file (recommended):

OPENCODE_USER_EMAIL=[email protected]

Or export in your shell:

export [email protected]

If not set, the system username is used as fallback.

Configuration Options

Required Fields

Field	Description
csv_file	Path to the CSV output file (supports ~/, absolute, or relative paths)
global_default.issue_key	Default JIRA issue key when no ticket found in context
global_default.account_key	Default Tempo account key for time entries

Optional Fields

Agent-specific Defaults

Override default ticket/account for specific agents:

{
  "time_tracking": {
    "csv_file": "...",
    "global_default": {
      "issue_key": "PROJ-MISC",
      "account_key": "TD_GENERAL"
    },
    "agent_defaults": {
      "@developer": {
        "issue_key": "PROJ-DEV",
        "account_key": "TD_DEVELOPMENT"
      },
      "@reviewer": {
        "issue_key": "PROJ-REVIEW"
      }
    }
  }
}

Ignored Agents

Skip time tracking for specific agents:

{
  "time_tracking": {
    "csv_file": "...",
    "global_default": { ... },
    "ignored_agents": ["@internal", "@notrack"]
  }
}

Project Whitelist

Restrict ticket detection to specific JIRA projects:

{
  "time_tracking": {
    "csv_file": "...",
    "global_default": { ... },
    "valid_projects": ["PROJ", "SOSO", "FEAT"]
  }
}

Full Example

{
  "$schema": "https://raw.githubusercontent.com/techdivision/opencode-plugins/main/schemas/opencode-project.json",
  "time_tracking": {
    "csv_file": "~/time_tracking/time-tracking.csv",
    "global_default": {
      "issue_key": "PROJ-MISC",
      "account_key": "TD_GENERAL"
    },
    "agent_defaults": {
      "@developer": {
        "issue_key": "PROJ-DEV",
        "account_key": "TD_DEVELOPMENT"
      },
      "@reviewer": {
        "issue_key": "PROJ-REVIEW"
      }
    },
    "ignored_agents": ["@internal"],
    "valid_projects": ["PROJ", "SOSO"]
  }
}

Ticket Detection

Pattern

By default, tickets must have at least 2 uppercase letters followed by a number:

• Matches: PROJ-123, SOSO-1, AB-99
• Does not match: V-1, X-9 (single letter), UTF-8 (common false positive)

Project Whitelist

When valid_projects is configured, only tickets from those projects are recognized:

{
  "time_tracking": {
    "valid_projects": ["PROJ", "SOSO", "FEAT"]
  }
}

With whitelist:

• Matches: PROJ-123, SOSO-1, FEAT-99
• Does not match: UTF-8, ISO-9001, OTHER-123

Without whitelist (default):

• Matches any pattern with 2+ uppercase letters: PROJ-123, AB-1
• Does not match single-letter prefixes: V-1, X-99

Fallback Hierarchy

Ticket Resolution

1. Context ticket (from messages/todos)
2. Agent-specific issue_key (if configured)
3. global_default.issue_key

Account Key Resolution

1. Agent-specific account_key (if configured)
2. global_default.account_key

How it works

• Tracks tool executions during each session turn
• Extracts JIRA ticket from user messages or todos
• Writes CSV entry when session becomes idle
• Shows toast notification with tracked time

CSV Format

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

Events

Event	When triggered
session.idle	After each complete AI response (including all tool calls)