opencode-wakatime

To avoid API spam, the plugin implements a rate-limited heartbeat system:

• Rate Limit: 1 heartbeat per minute per project.
• Triggering: Heartbeats are processed when chat.message events occur or when tool completions are detected via message.part.updated.
• Session Lifecycle: The plugin sends a final heartbeat when the session becomes idle or ends.
• Data Flow: Tool execution $\rightarrow$ Extract changes $\rightarrow$ Heartbeat Queue $\rightarrow$ Rate Limiter $\rightarrow$ wakatime-cli $\rightarrow$ WakaTime API.

The plugin hooks into OpenCode's event system to track AI coding activity. It extracts specific data based on the tool being executed:

Heartbeats include the file path (Entity), the working directory (Project folder), net line changes (AI line changes), the category ai coding, and a plugin identifier.

To build and install the plugin from the source repository:

1. Clone the repository.
2. Install dependencies and build.
3. Run the install command.

When installed from source, the plugin is automatically loaded by OpenCode without additional configuration.

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

The plugin requires a WakaTime API key to send metrics. Ensure your API key is configured in ~/.wakatime.cfg (or $WAKATIME_HOME/.wakatime.cfg if the environment variable is set).

Your configuration file should look like this:

[settings]
api_key = waka_your_api_key_here

You can retrieve your key from the WakaTime Settings page.

While the plugin attempts to download and update wakatime-cli automatically, you can install it manually to ensure availability.

macOS:

brew install wakatime-cli

Other platforms: Download the latest release from the WakaTime CLI releases page.

You can install the plugin manually using npm. This method installs the plugin to ~/.config/opencode/plugin/wakatime.js.

To install or update, run:

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

The recommended way to install the plugin is by adding it to your opencode.json configuration file.

Add the following entry to your configuration:

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

After installing the plugin using opencode-wakatime --install, you must manually add your WakaTime API key to your local WakaTime configuration file to enable tracking.

1. Create or edit ~/.wakatime.cfg.
2. Add your API key under the [settings] section.

Configuration format:

[settings]
api_key = your-api-key-here

You can retrieve your API key at: https://wakatime.com/settings/api-key

Plugin not loading

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

Heartbeats not sending

1. Verify the API key in ~/.wakatime.cfg.
2. Verify wakatime-cli is functional by running wakatime-cli --version.
3. Enable debug logging by adding debug=true to ~/.wakatime.cfg and check ~/.wakatime/opencode.log.

CLI not downloading

1. Check network connectivity.
2. Verify write permissions to ~/.wakatime/ (or $WAKATIME_HOME/).
3. Manually install the CLI using brew install wakatime-cli or from WakaTime releases.

You can override the default WakaTime directory locations by setting the WAKATIME_HOME environment variable. This variable affects the output of getWakatimeHomeDir(), getWakatimeResourcesDir(), and getWakatimeConfigFilePath().

Supported formats for WAKATIME_HOME:

• ~: Resolves to the user's home directory.
• ~/path/to/dir: Resolves to a subdirectory within the user's home directory.
• /absolute/path/to/dir: Uses the specified absolute path.

Use isCliAvailable to check if the wakatime-cli is already installed or available in the system's global path.

import { isCliAvailable } from 'opencode-wakatime';

if (isCliAvailable()) {
  console.log('CLI is ready to use');
}

Use sendHeartbeats to send one or more heartbeats to WakaTime in a single CLI invocation. This is optimized for batch edits: the first heartbeat is passed via CLI arguments, and subsequent heartbeats are passed as a JSON array via stdin to the wakatime-cli using the --extra-heartbeats flag. This prevents spawning a new process for every single file change.

If you only need to send a single heartbeat, you can use the convenience function sendHeartbeat.

import { sendHeartbeats, type HeartbeatParams } from 'opencode-wakatime';

const heartbeats: HeartbeatParams[] = [
  {
    entity: '/path/to/file.ts',
    projectFolder: '/path/to/project',
    lineChanges: 10,
    category: 'ai coding',
    isWrite: true
  },
  {
    entity: '/path/to/other-file.ts',
    lineChanges: 5,
    category: 'ai coding'
  }
];

await sendHeartbeats(heartbeats);