opencode-wakatime

WakaTime plugin for OpenCode - Track your AI coding activity, lines of code, and time spent.

Inspired by claude-code-wakatime.

Features

Automatic CLI management - Downloads and updates wakatime-cli automatically
Detailed file tracking - Tracks additions/deletions from edit, write, patch, and multiedit tools
AI coding metrics - Sends --ai-line-changes for WakaTime AI coding analytics
Rate-limited heartbeats - 1 per minute to avoid API spam
Session lifecycle - Sends final heartbeat on session idle/end

Prerequisites

WakaTime API Key

Ensure you have a WakaTime API key configured in ~/.wakatime.cfg:

[settings]
api_key = waka_your_api_key_here

You can get your API key from WakaTime Settings.

WakaTime CLI (Optional)

The plugin will automatically download wakatime-cli if not found. However, you can also install it manually:

macOS:

brew install wakatime-cli

Other platforms: Download from WakaTime releases.

Installation

Via npm (recommended)

npm i -g opencode-wakatime
opencode-wakatime --install

This installs the plugin to ~/.config/opencode/plugin/wakatime.js.

To update, run the same commands again.

From source

git clone https://github.com/angristan/opencode-wakatime
cd opencode-wakatime
npm install && npm run build
node bin/cli.js --install

The plugin will be automatically loaded by OpenCode - no configuration needed.

How It Works

The plugin hooks into OpenCode's event system:

flowchart TB
    subgraph OpenCode["OpenCode"]
        A[Tool Execution<br/>edit, write, patch, multiedit] --> H1[tool.execute.after]
        B[Chat Activity] --> H2[chat.message]
        C[Session Events<br/>idle, end] --> H3[event]
    end

    subgraph Plugin["opencode-wakatime Plugin"]
        H1 --> P1[Extract File Changes<br/>path, additions, deletions]
        P1 --> Q[Heartbeat Queue]

        H2 -.->|triggers| P2[Process Queue]
        Q --> P2
        P2 --> R[Rate Limiter<br/>1 per minute]

        H3 --> P3[Flush Final<br/>Heartbeat]
        P3 --> R
    end

    subgraph WakaTime["WakaTime"]
        R --> CLI[wakatime-cli]
        CLI --> API[WakaTime API]
        API --> D[Dashboard<br/>AI Coding Metrics]
    end

Hooks Used

Hook	Purpose
`tool.execute.after`	Tracks file modifications from tools
`chat.message`	Triggers heartbeat processing on activity
`event`	Listens for session lifecycle events

Tool Tracking

Tool	Data Extracted
`edit`	File path, additions, deletions (from `filediff`)
`write`	File path, new file detection
`patch`	File paths from output, diff count
`multiedit`	File paths and changes from each edit result

Heartbeat Data

Each heartbeat includes:

Entity: File path being worked on
Project folder: Working directory
AI line changes: Net lines added/removed (additions - deletions)
Category: "ai coding"
Plugin identifier: opencode/1.0.0 opencode-wakatime/1.0.0

Files

File	Purpose
`~/.wakatime/opencode.log`	Debug logs
`~/.wakatime/opencode.json`	State (last heartbeat timestamp)
`~/.wakatime/opencode-cli-state.json`	CLI version tracking
`~/.wakatime/wakatime-cli-*`	Auto-downloaded CLI binary

Development

# Install dependencies
npm install

# Type check
npm run typecheck

# Build
npm run build

Troubleshooting

Plugin not loading

Check your config file syntax (opencode.jsonc)
Verify the plugin path is correct
Check logs at ~/.wakatime/opencode.log

Heartbeats not sending

Verify API key in ~/.wakatime.cfg
Check if wakatime-cli is working: wakatime-cli --version
Enable debug logging and check ~/.wakatime/opencode.log

CLI not downloading

Check network connectivity
Verify write permissions to ~/.wakatime/
Manually install: brew install wakatime-cli

License

MIT