opencode-wakatime

opencode-wakatime

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

Inspired by claude-code-wakatime.

[!TIP] Also check out codex-wakatime for OpenAI Codex CLI!

Features

• Automatic CLI management - Downloads and updates wakatime-cli automatically
• Detailed file tracking - Tracks file reads and modifications (edit, write, patch, multiedit)
• AI coding metrics - Sends --ai-line-changes for WakaTime AI coding analytics
• Rate-limited heartbeats - 1 per minute per project to avoid API spam
• Session lifecycle - Sends final heartbeat on session idle/end
• Batch tool support - Tracks file operations executed via batch tool

Prerequisites

WakaTime API Key

Ensure you have a WakaTime API key configured in ~/.wakatime.cfg (or $WAKATIME_HOME/.wakatime.cfg when WAKATIME_HOME is set):

[settings]
api_key = waka_your_api_key_here

You can get your API key from WakaTime Settings.

WakaTime CLI (Optional)

In case of manual install, the plugin will automatically download wakatime-cli if not found. However, you can also install it yourself:

macOS:

brew install wakatime-cli

Other platforms: Download from WakaTime releases.

Installation

Via opencode config (recommended)

opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-wakatime"]
}

Manually via npm

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:

…

Hooks Used

Tool Tracking

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-/ opencode-wakatime/ (e.g. opencode-desktop/1.1.53 opencode-wakatime/1.1.4)

Files

By default, plugin files are stored in ~/.wakatime/. When WAKATIME_HOME is set, the same files are stored in $WAKATIME_HOME/.

Development

# Install dependencies
npm install

# Type check
npm run typecheck

# Build
npm run build

Troubleshooting

Plugin not loading

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

Heartbeats not sending

1. Verify API key in ~/.wakatime.cfg
2. Check if wakatime-cli is working: wakatime-cli --version
3. Enable debug logging and check ~/.wakatime/opencode.log (or $WAKATIME_HOME/opencode.log when set)

CLI not downloading

1. Check network connectivity
2. Verify write permissions to ~/.wakatime/ (or $WAKATIME_HOME/ when set)
3. Manually install: brew install wakatime-cli

License

MIT