@techdivision/opencode-time-tracking 0.2.0 → 0.3.0

package/README.md

@@ -14,6 +14,8 @@ Add to your `opencode.json`:
 
 ## Configuration
 
+### 1. Project Configuration
+
 Add the `time_tracking` section to your `.opencode/opencode-project.json`:
 
 ```json
@@ -21,12 +23,29 @@ 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",
-    "user_email": "your@email.com",
     "default_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):
+
+```env
+OPENCODE_USER_EMAIL=your@email.com
+```
+
+Or export in your shell:
+
+```bash
+export OPENCODE_USER_EMAIL=your@email.com
+```
+
+If not set, the system username is used as fallback.
+
 ## How it works
 
 - Tracks tool executions during each session turn

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techdivision/opencode-time-tracking",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Automatic time tracking plugin for OpenCode - tracks session duration and tool usage to CSV",
   "main": "src/Plugin.ts",
   "types": "src/Plugin.ts",

package/src/Plugin.ts

@@ -25,20 +25,27 @@ import { createToolExecuteAfterHook } from "./hooks/ToolExecuteAfterHook"
  * - Token consumption (input/output/reasoning tokens)
  * - Ticket references (extracted from user messages or todos)
  *
- * Data is exported to a CSV file configured in `.opencode/time-tracking.json`.
+ * Data is exported to a CSV file configured in `.opencode/opencode-project.json`.
  *
  * @param input - Plugin input containing client, directory, and other context
  * @returns Hooks object with event and tool.execute.after handlers
  *
  * @example
  * ```json
- * // .opencode/time-tracking.json
+ * // .opencode/opencode-project.json
  * {
- *   "csv_file": "~/worklogs/time.csv",
- *   "user_email": "user@example.com",
- *   "default_account_key": "ACCOUNT-1"
+ *   "time_tracking": {
+ *     "csv_file": "~/worklogs/time.csv",
+ *     "default_account_key": "ACCOUNT-1"
+ *   }
  * }
  * ```
+ *
+ * @example
+ * ```bash
+ * # .env - Set user email via environment variable
+ * OPENCODE_USER_EMAIL=user@example.com
+ * ```
  */
 export const plugin: Plugin = async ({
   client,
@@ -48,7 +55,6 @@ export const plugin: Plugin = async ({
 
   if (!config) {
     // Silently return empty hooks if no config found
-    // Toast notifications don't work during plugin initialization
     return {}
   }
 

package/src/hooks/EventHook.ts

@@ -105,11 +105,17 @@ export function createEventHook(
       return
     }
 
-    // Track token usage from step-finish events
+    // Track token usage and agent from message part events
     if (event.type === "message.part.updated") {
       const props = event.properties as MessagePartUpdatedProperties
       const part = props.part
 
+      // Track agent from agent parts (only first agent is stored)
+      if (part.type === "agent" && part.sessionID && part.name) {
+        sessionManager.setAgent(part.sessionID, part.name)
+      }
+
+      // Track token usage from step-finish events
       if (part.type === "step-finish" && part.sessionID && part.tokens) {
         sessionManager.addTokenUsage(part.sessionID, {
           input: part.tokens.input,
@@ -161,6 +167,9 @@ export function createEventHook(
         ? `${session.model.providerID}/${session.model.modelID}`
         : null
 
+      // Get agent name if available
+      const agentString = session.agent?.name ?? null
+
       try {
         await csvWriter.write({
           ticket: session.ticket,
@@ -171,6 +180,7 @@ export function createEventHook(
           notes: `Auto-tracked: ${toolSummary}`,
           tokenUsage: session.tokenUsage,
           model: modelString,
+          agent: agentString,
         })
 
         const minutes = Math.round(durationSeconds / 60)

package/src/services/ConfigLoader.ts

@@ -2,6 +2,8 @@
  * @fileoverview Configuration loader for the time tracking plugin.
  */
 
+import { userInfo } from "os"
+
 import type {
   OpencodeProjectConfig,
   TimeTrackingConfig,
@@ -9,12 +11,21 @@ import type {
 
 import "../types/Bun"
 
+/**
+ * Environment variable name for user email.
+ */
+const ENV_USER_EMAIL = "OPENCODE_USER_EMAIL"
+
 /**
  * Loads the plugin configuration from the project directory.
  *
  * @remarks
  * The configuration file is expected at `.opencode/opencode-project.json`
  * within the project directory, with a `time_tracking` section.
+ *
+ * The `user_email` is resolved from:
+ * 1. `OPENCODE_USER_EMAIL` environment variable
+ * 2. System username (fallback)
  */
 export class ConfigLoader {
   /**
@@ -28,6 +39,7 @@ export class ConfigLoader {
    * const config = await ConfigLoader.load("/path/to/project")
    * if (config) {
    *   console.log(config.csv_file)
+   *   console.log(config.user_email) // Resolved from ENV or system username
    * }
    * ```
    */
@@ -41,7 +53,15 @@ export class ConfigLoader {
         const projectConfig = (await file.json()) as OpencodeProjectConfig
 
         if (projectConfig.time_tracking) {
-          return projectConfig.time_tracking
+          const jsonConfig = projectConfig.time_tracking
+
+          // Resolve user_email from environment variable or fallback to system username
+          const userEmail = process.env[ENV_USER_EMAIL] || userInfo().username
+
+          return {
+            ...jsonConfig,
+            user_email: userEmail,
+          }
         }
       }
 

package/src/services/CsvWriter.ts

@@ -18,7 +18,7 @@ import "../types/Bun"
  * Compatible with Jira/Tempo time tracking import.
  */
 const 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"
+  "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"
 
 /**
  * Writes time tracking entries to a CSV file.
@@ -123,6 +123,7 @@ export class CsvWriter {
       CsvFormatter.escape(data.description),
       CsvFormatter.escape(data.notes),
       data.model ?? "",
+      data.agent ?? "",
     ]
 
     const csvLine = fields.map((f) => `"${f}"`).join(",")

package/src/services/SessionManager.ts

@@ -3,6 +3,7 @@
  */
 
 import type { ActivityData } from "../types/ActivityData"
+import type { AgentInfo } from "../types/AgentInfo"
 import type { ModelInfo } from "../types/ModelInfo"
 import type { SessionData } from "../types/SessionData"
 import type { TokenUsage } from "../types/TokenUsage"
@@ -63,6 +64,7 @@ export class SessionManager {
         cacheWrite: 0,
       },
       model: null,
+      agent: null,
     }
 
     this.sessions.set(sessionID, session)
@@ -146,4 +148,26 @@ export class SessionManager {
       session.model = model
     }
   }
+
+  /**
+   * Sets the agent for a session.
+   *
+   * @param sessionID - The OpenCode session identifier
+   * @param agentName - The agent name (e.g., "@developer")
+   *
+   * @remarks
+   * Only sets the agent if it hasn't been set yet.
+   * The first agent detected in a session is used (primary agent).
+   */
+  setAgent(sessionID: string, agentName: string): void {
+    const session = this.sessions.get(sessionID)
+
+    if (session && !session.agent) {
+      const agent: AgentInfo = {
+        name: agentName,
+        timestamp: Date.now(),
+      }
+      session.agent = agent
+    }
+  }
 }

package/src/types/AgentInfo.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Agent information type for tracking which agent executed work.
+ */
+
+/**
+ * Information about an agent that was active during a session.
+ */
+export interface AgentInfo {
+  /** The agent name (e.g., "@developer", "@reviewer") */
+  name: string
+
+  /** Unix timestamp in milliseconds when the agent became active */
+  timestamp: number
+}

package/src/types/CsvEntryData.ts

@@ -36,4 +36,13 @@ export interface CsvEntryData {
    * Examples: `anthropic/claude-opus-4`, `openai/gpt-5`
    */
   model: string | null
+
+  /**
+   * Agent name that performed the work.
+   *
+   * @remarks
+   * Examples: `@developer`, `@reviewer`
+   * Only the first/primary agent is tracked.
+   */
+  agent: string | null
 }

package/src/types/MessagePartUpdatedProperties.ts

@@ -10,13 +10,16 @@ import type { StepFinishPart } from "./StepFinishPart"
 export interface MessagePartUpdatedProperties {
   /** The updated message part */
   part: {
-    /** The type of the part */
+    /** The type of the part (e.g., "step-finish", "agent") */
     type: string
 
-    /** Session ID (present on step-finish parts) */
+    /** Session ID (present on step-finish and agent parts) */
     sessionID?: string
 
     /** Token usage (present on step-finish parts) */
     tokens?: StepFinishPart["tokens"]
+
+    /** Agent name (present on agent parts) */
+    name?: string
   }
 }

package/src/types/SessionData.ts

@@ -3,6 +3,7 @@
  */
 
 import type { ActivityData } from "./ActivityData"
+import type { AgentInfo } from "./AgentInfo"
 import type { ModelInfo } from "./ModelInfo"
 import type { TokenUsage } from "./TokenUsage"
 
@@ -24,4 +25,7 @@ export interface SessionData {
 
   /** Model used in this session, or `null` if not detected */
   model: ModelInfo | null
+
+  /** First agent used in this session, or `null` if not detected */
+  agent: AgentInfo | null
 }

package/src/types/TimeTrackingConfig.ts

@@ -3,9 +3,14 @@
  */
 
 /**
- * Time tracking configuration from `.opencode/opencode-project.json`.
+ * Time tracking configuration as stored in `.opencode/opencode-project.json`.
+ *
+ * @remarks
+ * The `user_email` field is not stored in the JSON file.
+ * It is resolved from `OPENCODE_USER_EMAIL` environment variable
+ * or falls back to the system username.
  */
-export interface TimeTrackingConfig {
+export interface TimeTrackingJsonConfig {
   /**
    * Path to the CSV output file.
    *
@@ -17,13 +22,28 @@ export interface TimeTrackingConfig {
    */
   csv_file: string
 
-  /** Email address of the user for the worklog */
-  user_email: string
-
   /** Default Jira account key for time entries */
   default_account_key: string
 }
 
+/**
+ * Resolved time tracking configuration used at runtime.
+ *
+ * @remarks
+ * Extends `TimeTrackingJsonConfig` with the resolved `user_email` field.
+ */
+export interface TimeTrackingConfig extends TimeTrackingJsonConfig {
+  /**
+   * User email for the worklog.
+   *
+   * @remarks
+   * Resolved from (in order of priority):
+   * 1. `OPENCODE_USER_EMAIL` environment variable
+   * 2. System username (via `os.userInfo().username`)
+   */
+  user_email: string
+}
+
 /**
  * OpenCode project configuration structure.
  */
@@ -32,5 +52,5 @@ export interface OpencodeProjectConfig {
   $schema?: string
 
   /** Time tracking configuration */
-  time_tracking?: TimeTrackingConfig
+  time_tracking?: TimeTrackingJsonConfig
 }