opencode-time-tracking 0.1.5

package/AGENTS.md

@@ -0,0 +1,247 @@
+# AGENTS.md - OpenCode Time Tracking Plugin
+
+Guidelines for AI agents working in this repository.
+
+## Project Overview
+
+OpenCode plugin that automatically tracks session duration, tool usage, and token consumption, exporting data to CSV for time tracking integration (e.g., Jira/Tempo).
+
+## Build & Development Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Type check (no emit)
+npx tsc --noEmit
+
+# Watch mode for development
+npx tsc --noEmit --watch
+```
+
+**Note:** This is a Bun-based plugin. No build step required - TypeScript files are loaded directly by OpenCode at runtime.
+
+## Project Structure
+
+```
+src/
+├── Plugin.ts                 # Main entry point, exports plugin
+├── hooks/                    # OpenCode hook implementations
+│   ├── EventHook.ts          # Session events (idle, deleted, token tracking)
+│   └── ToolExecuteAfterHook.ts  # Tool execution tracking
+├── services/                 # Business logic classes
+│   ├── ConfigLoader.ts       # Load plugin configuration
+│   ├── CsvWriter.ts          # CSV file output
+│   ├── SessionManager.ts     # Session state management
+│   └── TicketExtractor.ts    # Extract tickets from messages/todos
+├── types/                    # TypeScript interfaces (one per file)
+│   ├── ActivityData.ts
+│   ├── SessionData.ts
+│   ├── TokenUsage.ts
+│   └── ...
+└── utils/                    # Utility classes
+    ├── CsvFormatter.ts       # CSV formatting helpers
+    └── DescriptionGenerator.ts  # Generate activity descriptions
+```
+
+## Code Style Guidelines
+
+### File Organization
+
+**CRITICAL: One class/interface/function per file using PascalCase naming.**
+
+```
+# Good
+src/types/TokenUsage.ts       → export interface TokenUsage
+src/services/SessionManager.ts → export class SessionManager
+src/hooks/EventHook.ts        → export function createEventHook
+
+# Bad - multiple exports in one file
+src/types/index.ts            → export interface A, B, C  // NO!
+```
+
+### Imports
+
+- Use `import type` for type-only imports
+- Group imports: external packages first, then internal modules
+- Use relative paths for internal imports
+
+```typescript
+// External packages first
+import type { Plugin, Hooks, PluginInput } from "@opencode-ai/plugin"
+import type { Event } from "@opencode-ai/sdk"
+
+// Internal imports
+import type { SessionManager } from "../services/SessionManager"
+import { DescriptionGenerator } from "../utils/DescriptionGenerator"
+```
+
+### TypeScript
+
+- Strict mode enabled (`"strict": true`)
+- Target: ESNext
+- Module resolution: bundler
+- No emit - TypeScript is for type checking only
+- Explicit return types on public methods
+- Use `interface` for object shapes, `type` for unions/aliases
+
+```typescript
+// Interface for object shapes
+export interface TokenUsage {
+  input: number
+  output: number
+}
+
+// Type for unions or derived types
+type OpencodeClient = ReturnType<typeof createOpencodeClient>
+```
+
+### Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Files | PascalCase | `SessionManager.ts` |
+| Classes | PascalCase | `class SessionManager` |
+| Interfaces | PascalCase | `interface TokenUsage` |
+| Functions | camelCase | `createEventHook()` |
+| Variables | camelCase | `sessionManager` |
+| Constants | UPPER_SNAKE_CASE | `TICKET_PATTERN` |
+| Private members | camelCase with `private` | `private sessions` |
+
+### Error Handling
+
+- Use try/catch with empty catch blocks for graceful degradation
+- Return `null` on failure rather than throwing
+- Log errors via toast notifications to user
+
+```typescript
+try {
+  const result = await client.session.messages(...)
+  // ...
+} catch {
+  return null  // Graceful fallback
+}
+```
+
+### Class Structure
+
+```typescript
+export class ServiceName {
+  // Private fields first
+  private client: OpencodeClient
+
+  // Constructor
+  constructor(client: OpencodeClient) {
+    this.client = client
+  }
+
+  // Public methods
+  async publicMethod(): Promise<string | null> {
+    // ...
+  }
+
+  // Private methods last
+  private helperMethod(): void {
+    // ...
+  }
+}
+```
+
+### Hook Factory Pattern
+
+Hooks are created via factory functions that receive dependencies:
+
+```typescript
+export function createEventHook(
+  sessionManager: SessionManager,
+  csvWriter: CsvWriter,
+  client: OpencodeClient
+) {
+  return async ({ event }: { event: Event }): Promise<void> => {
+    // Hook implementation
+  }
+}
+```
+
+## OpenCode SDK Usage
+
+### Client API Calls
+
+Use `path` parameter for session-specific endpoints:
+
+```typescript
+// Correct
+const result = await client.session.messages({
+  path: { id: sessionID },
+} as Parameters<typeof client.session.messages>[0])
+
+// Access data
+const messages = result.data as MessageWithParts[]
+```
+
+### Plugin Export
+
+Must export a named `plugin` constant:
+
+```typescript
+export const plugin: Plugin = async ({ client, directory }: PluginInput): Promise<Hooks> => {
+  return {
+    "tool.execute.after": createToolExecuteAfterHook(...),
+    event: createEventHook(...),
+  }
+}
+
+export default plugin
+```
+
+## Configuration
+
+Plugin config file: `.opencode/time-tracking.json`
+
+```json
+{
+  "csv_file": "~/worklogs/time.csv",
+  "user_email": "user@example.com",
+  "default_account_key": "ACCOUNT-1"
+}
+```
+
+## Git Workflow (Gitflow)
+
+This project follows **Gitflow**:
+
+- **main**: Production-ready releases only
+- **develop**: Integration branch for features
+- Feature branches: `feature/<name>` (branch from `develop`)
+- Release branches: `release/<version>` (branch from `develop`)
+- Hotfix branches: `hotfix/<name>` (branch from `main`)
+
+### Release Process
+
+**CRITICAL: When creating a new release, ALWAYS:**
+
+1. Update `version` in `package.json`
+2. Commit the version bump
+3. Merge `develop` into `main`
+4. Create annotated tag: `git tag -a vX.Y.Z -m "vX.Y.Z - Description"`
+5. Push both branches and tag
+
+```bash
+# Example release workflow
+git checkout develop
+# ... make changes ...
+git add . && git commit -m "Your changes"
+
+# Update version in package.json
+# Edit package.json: "version": "X.Y.Z"
+git add package.json && git commit -m "Bump version to X.Y.Z"
+
+# Merge to main and tag
+git checkout main
+git merge develop
+git tag -a vX.Y.Z -m "vX.Y.Z - Release description"
+
+# Push everything
+git push origin main develop
+git push origin vX.Y.Z
+```

package/README.md

@@ -0,0 +1,45 @@
+# 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`:
+
+```json
+{
+  "plugin": ["opencode-time-tracking"]
+}
+```
+
+## Configuration
+
+Create `.opencode/time-tracking.json` in your project:
+
+```json
+{
+  "csv_file": "~/time_tracking/time-tracking.csv",
+  "user_email": "your@email.com",
+  "default_account_key": "YOUR_ACCOUNT_KEY"
+}
+```
+
+## How it works
+
+- Tracks tool executions during each session turn
+- Extracts JIRA ticket from git branch name (e.g., `feature/PROJ-123-description`)
+- Writes CSV entry when session becomes idle (after each complete response)
+- 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) |
+| `session.deleted` | When a session is explicitly deleted |

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "opencode-time-tracking",
+  "version": "0.1.5",
+  "description": "Automatic time tracking plugin for OpenCode - tracks session duration and tool usage to CSV",
+  "main": "src/Plugin.ts",
+  "types": "src/Plugin.ts",
+  "keywords": [
+    "opencode",
+    "plugin",
+    "time-tracking",
+    "jira"
+  ],
+  "author": "TechDivision",
+  "license": "MIT",
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.0.223"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^25.0.3",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/Plugin.ts

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview OpenCode Time Tracking Plugin
+ *
+ * Automatically tracks session duration, tool usage, and token consumption,
+ * exporting data to CSV for time tracking integration (e.g., Jira/Tempo).
+ *
+ * @packageDocumentation
+ */
+
+import type { Plugin, Hooks, PluginInput } from "@opencode-ai/plugin"
+
+import { ConfigLoader } from "./services/ConfigLoader"
+import { CsvWriter } from "./services/CsvWriter"
+import { SessionManager } from "./services/SessionManager"
+import { TicketExtractor } from "./services/TicketExtractor"
+import { createEventHook } from "./hooks/EventHook"
+import { createToolExecuteAfterHook } from "./hooks/ToolExecuteAfterHook"
+
+/**
+ * OpenCode Time Tracking Plugin
+ *
+ * This plugin automatically tracks:
+ * - Session duration (start/end time)
+ * - Tool usage (which tools were called)
+ * - 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`.
+ *
+ * @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
+ * {
+ *   "csv_file": "~/worklogs/time.csv",
+ *   "user_email": "user@example.com",
+ *   "default_account_key": "ACCOUNT-1"
+ * }
+ * ```
+ */
+export const plugin: Plugin = async ({
+  client,
+  directory,
+}: PluginInput): Promise<Hooks> => {
+  const config = await ConfigLoader.load(directory)
+
+  if (!config) {
+    // Silently return empty hooks if no config found
+    // Toast notifications don't work during plugin initialization
+    return {}
+  }
+
+  const sessionManager = new SessionManager()
+  const csvWriter = new CsvWriter(config, directory)
+  const ticketExtractor = new TicketExtractor(client)
+
+  const hooks: Hooks = {
+    "tool.execute.after": createToolExecuteAfterHook(
+      sessionManager,
+      ticketExtractor
+    ),
+    event: createEventHook(sessionManager, csvWriter, client),
+  }
+
+  return hooks
+}

package/src/hooks/EventHook.ts

@@ -0,0 +1,163 @@
+/**
+ * @fileoverview Event hook for session lifecycle and token tracking.
+ */
+
+import type { Event } from "@opencode-ai/sdk"
+
+import type { CsvWriter } from "../services/CsvWriter"
+import type { SessionManager } from "../services/SessionManager"
+import type { MessagePartUpdatedProperties } from "../types/MessagePartUpdatedProperties"
+import type { MessageWithParts } from "../types/MessageWithParts"
+import type { OpencodeClient } from "../types/OpencodeClient"
+
+import { DescriptionGenerator } from "../utils/DescriptionGenerator"
+
+/**
+ * Extracts the summary title from the last user message.
+ *
+ * @param client - The OpenCode SDK client
+ * @param sessionID - The session identifier
+ * @returns The summary title, or `null` if not found
+ *
+ * @internal
+ */
+async function extractSummaryTitle(
+  client: OpencodeClient,
+  sessionID: string
+): Promise<string | null> {
+  try {
+    const result = await client.session.messages({
+      path: { id: sessionID },
+    } as Parameters<typeof client.session.messages>[0])
+
+    if (!result.data) {
+      return null
+    }
+
+    const messages = result.data as MessageWithParts[]
+
+    // Find the last user message with a summary title
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const message = messages[i]
+
+      if (message.info.role === "user" && message.info.summary?.title) {
+        return message.info.summary.title
+      }
+    }
+
+    return null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Creates the event hook for session lifecycle management.
+ *
+ * @param sessionManager - The session manager instance
+ * @param csvWriter - The CSV writer instance
+ * @param client - The OpenCode SDK client
+ * @returns The event hook function
+ *
+ * @remarks
+ * Handles two types of events:
+ *
+ * 1. **message.part.updated** - Tracks token usage from step-finish parts
+ * 2. **session.idle** - Finalizes and exports the session
+ *
+ * @example
+ * ```typescript
+ * const hooks: Hooks = {
+ *   event: createEventHook(sessionManager, csvWriter, client),
+ * }
+ * ```
+ */
+export function createEventHook(
+  sessionManager: SessionManager,
+  csvWriter: CsvWriter,
+  client: OpencodeClient
+) {
+  return async ({ event }: { event: Event }): Promise<void> => {
+    // Track token usage from step-finish events
+    if (event.type === "message.part.updated") {
+      const props = event.properties as MessagePartUpdatedProperties
+      const part = props.part
+
+      if (part.type === "step-finish" && part.sessionID && part.tokens) {
+        sessionManager.addTokenUsage(part.sessionID, {
+          input: part.tokens.input,
+          output: part.tokens.output,
+          reasoning: part.tokens.reasoning,
+          cacheRead: part.tokens.cache.read,
+          cacheWrite: part.tokens.cache.write,
+        })
+      }
+
+      return
+    }
+
+    // Handle session idle events (only log on idle, not on deleted)
+    if (event.type === "session.idle") {
+      const props = event.properties as { sessionID?: string }
+      const sessionID = props.sessionID
+
+      if (!sessionID) {
+        return
+      }
+
+      const session = sessionManager.get(sessionID)
+
+      if (!session || session.activities.length === 0) {
+        sessionManager.delete(sessionID)
+        return
+      }
+
+      const endTime = Date.now()
+      const durationSeconds = Math.round((endTime - session.startTime) / 1000)
+
+      // Try to get summary title from messages, fallback to generated description
+      const summaryTitle = await extractSummaryTitle(client, sessionID)
+      const description =
+        summaryTitle || DescriptionGenerator.generate(session.activities)
+
+      const toolSummary = DescriptionGenerator.generateToolSummary(
+        session.activities
+      )
+
+      const totalTokens =
+        session.tokenUsage.input +
+        session.tokenUsage.output +
+        session.tokenUsage.reasoning
+
+      try {
+        await csvWriter.write({
+          ticket: session.ticket,
+          startTime: session.startTime,
+          endTime,
+          durationSeconds,
+          description,
+          notes: `Auto-tracked: ${toolSummary}`,
+          tokenUsage: session.tokenUsage,
+        })
+
+        const minutes = Math.round(durationSeconds / 60)
+
+        await client.tui.showToast({
+          body: {
+            message: `Time tracked: ${minutes} min, ${totalTokens} tokens${session.ticket ? ` for ${session.ticket}` : ""}`,
+            variant: "success",
+          },
+        })
+      } catch {
+        await client.tui.showToast({
+          body: {
+            message: "Time Tracking: Failed to save entry",
+            variant: "error",
+          },
+        })
+        }
+
+      sessionManager.delete(sessionID)
+    }
+  }
+}

package/src/hooks/ToolExecuteAfterHook.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Hook for tracking tool executions.
+ */
+
+import type { SessionManager } from "../services/SessionManager"
+import type { TicketExtractor } from "../services/TicketExtractor"
+import type { ToolExecuteAfterInput } from "../types/ToolExecuteAfterInput"
+import type { ToolExecuteAfterOutput } from "../types/ToolExecuteAfterOutput"
+
+/**
+ * Creates the tool.execute.after hook for activity tracking.
+ *
+ * @param sessionManager - The session manager instance
+ * @param ticketExtractor - The ticket extractor instance
+ * @returns The hook function
+ *
+ * @remarks
+ * This hook is called after every tool execution and:
+ *
+ * 1. Creates a new session if one doesn't exist
+ * 2. Extracts and updates the ticket reference from context
+ * 3. Records the tool activity with timestamp and file info
+ *
+ * @example
+ * ```typescript
+ * const hooks: Hooks = {
+ *   "tool.execute.after": createToolExecuteAfterHook(sessionManager, ticketExtractor),
+ * }
+ * ```
+ */
+export function createToolExecuteAfterHook(
+  sessionManager: SessionManager,
+  ticketExtractor: TicketExtractor
+) {
+  return async (
+    input: ToolExecuteAfterInput,
+    output: ToolExecuteAfterOutput
+  ): Promise<void> => {
+    const { tool, sessionID } = input
+    const { title, metadata } = output
+
+    // Create session if it doesn't exist
+    if (!sessionManager.has(sessionID)) {
+      sessionManager.create(sessionID, null)
+    }
+
+    // Extract and update ticket on every tool call
+    const ticket = await ticketExtractor.extract(sessionID)
+    sessionManager.updateTicket(sessionID, ticket)
+
+    // Extract file info from metadata
+    let file: string | undefined
+
+    if (metadata) {
+      const meta = metadata as Record<string, unknown>
+
+      file = (meta.filePath || meta.filepath || meta.file) as
+        | string
+        | undefined
+
+      if (!file && meta.filediff) {
+        file = (meta.filediff as Record<string, unknown>).file as
+          | string
+          | undefined
+      }
+    }
+
+    if (!file && title) {
+      file = title
+    }
+
+    sessionManager.addActivity(sessionID, {
+      tool,
+      timestamp: Date.now(),
+      file,
+    })
+  }
+}

package/src/services/ConfigLoader.ts

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Configuration loader for the time tracking plugin.
+ */
+
+import type { TimeTrackingConfig } from "../types/TimeTrackingConfig"
+
+import "../types/Bun"
+
+/**
+ * Loads the plugin configuration from the project directory.
+ *
+ * @remarks
+ * The configuration file is expected at `.opencode/time-tracking.json`
+ * within the project directory.
+ */
+export class ConfigLoader {
+  /**
+   * Loads the time tracking configuration from the filesystem.
+   *
+   * @param directory - The project directory path
+   * @returns The configuration object, or `null` if not found or invalid
+   *
+   * @example
+   * ```typescript
+   * const config = await ConfigLoader.load("/path/to/project")
+   * if (config) {
+   *   console.log(config.csv_file)
+   * }
+   * ```
+   */
+  static async load(directory: string): Promise<TimeTrackingConfig | null> {
+    const configPath = `${directory}/.opencode/time-tracking.json`
+
+    try {
+      const file = Bun.file(configPath)
+
+      if (await file.exists()) {
+        return (await file.json()) as TimeTrackingConfig
+      }
+
+      return null
+    } catch {
+      return null
+    }
+  }
+}