https://github.com/angristan/opencode-wakatime
Track Opencode usage with Wakatime
https://github.com/angristan/opencode-wakatime
coding-agent opencode opencode-plugin wakatime
Last synced: about 5 hours ago
JSON representation
Track Opencode usage with Wakatime
- Host: GitHub
- URL: https://github.com/angristan/opencode-wakatime
- Owner: angristan
- License: mit
- Created: 2025-12-04T23:05:47.000Z (3 months ago)
- Default Branch: master
- Last Pushed: 2026-01-30T17:49:50.000Z (24 days ago)
- Last Synced: 2026-01-31T11:33:51.785Z (24 days ago)
- Topics: coding-agent, opencode, opencode-plugin, wakatime
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/opencode-wakatime
- Size: 175 KB
- Stars: 58
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# opencode-wakatime
[](https://www.npmjs.com/package/opencode-wakatime)
[](https://www.npmjs.com/package/opencode-wakatime)
[](https://github.com/angristan/opencode-wakatime/actions/workflows/workflow.yml)
[](LICENSE)
WakaTime plugin for [OpenCode](https://github.com/sst/opencode) - Track your AI coding activity, lines of code, and time spent.
Inspired by [claude-code-wakatime](https://github.com/wakatime/claude-code-wakatime).
> [!TIP]
> Also check out [codex-wakatime](https://github.com/angristan/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`:
```ini
[settings]
api_key = waka_your_api_key_here
```
You can get your API key from [WakaTime Settings](https://wakatime.com/api-key).
### 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:**
```bash
brew install wakatime-cli
```
**Other platforms:**
Download from [WakaTime releases](https://github.com/wakatime/wakatime-cli/releases/latest).
## Installation
### Via opencode config (recommended)
opencode.json:
```json
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["opencode-wakatime"]
}
```
### Manually via npm
```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.
### From source
```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
```
### Hooks Used
| Hook | Purpose |
| -------------- | ---------------------------------------------------------------- |
| `event` | Tracks tool completions via `message.part.updated` and session lifecycle |
| `chat.message` | Triggers heartbeat processing on activity |
### Tool Tracking
| 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 |
### 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
| File | Purpose |
| ------------------------------------- | ------------------------------------------ |
| `~/.wakatime/opencode.log` | Debug logs (enabled via `debug=true` in `~/.wakatime.cfg`) |
| `~/.wakatime/opencode-{hash}.json` | Per-project state (last heartbeat timestamp) |
| `~/.wakatime/opencode-cli-state.json` | CLI version tracking |
| `~/.wakatime/opencode-version-cache.json` | Cached OpenCode server version |
| `~/.wakatime/wakatime-cli-*` | Auto-downloaded CLI binary |
## Development
```bash
# 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`
### CLI not downloading
1. Check network connectivity
2. Verify write permissions to `~/.wakatime/`
3. Manually install: `brew install wakatime-cli`
## License
MIT