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

$3

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

``ini
[settings]
api_key = waka_your_api_key_here
`

You can get your API key from WakaTime Settings.

$3

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

macOS:

`bash
brew install wakatime-cli
`

Other platforms:
Download from WakaTime releases.

Installation

$3

opencode.json:

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

$3

`bash
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.

$3

`bash
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:

`mermaid
flowchart TB
subgraph OpenCode["OpenCode"]
A[Tool Execution
read, edit, write, patch, multiedit, batch] --> H1[message.part.updated]
B[Chat Activity] --> H2[chat.message]
C[Session Events
idle, end] --> H3[event]
end

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

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

H3 --> P3[Flush Final
Heartbeat]
P3 --> R
end

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

`

$3

| Hook | Purpose |
| -------------- | ---------------------------------------------------------------- |
| event | Tracks tool completions via message.part.updated and session lifecycle |
| chat.message | Triggers heartbeat processing on activity |

$3

| Tool | Data Extracted |
| ----------- | ------------------------------------------------- |
| read | File path (from title) |
| 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 |
| batch | Tracks all child tool operations |

$3

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-{hash}.json | Per-project state (last heartbeat timestamp) |
| ~/.wakatime/opencode-cli-state.json | CLI version tracking |
| ~/.wakatime/wakatime-cli-* | Auto-downloaded CLI binary |

Development

`bash


Install dependencies

npm install

Type check

npm run typecheck

Build

npm run build
`

Troubleshooting

$3

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

$3

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

$3

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

License

MIT