omp-wakatime

omp-wakatime

WakaTime activity tracking extension for Oh My Pi / @oh-my-pi/pi-coding-agent.

omp-wakatime tracks OMP session activity and file operations through wakatime-cli, including WakaTime AI coding metrics for edits.

Features

• OMP-native extension via omp.extensions.
• Tracks session_start, tool_result, and session_shutdown.
• Sends synthetic session activity as <project>/.omp-session.
• Tracks file activity for read, write, edit, and ast_edit.
• Reports AI line changes with --ai-line-changes for write/edit/ast_edit.
• Uses wakatime-cli, ~/.wakatime.cfg, and $WAKATIME_HOME conventions.
• Finds global wakatime-cli; otherwise downloads a local CLI into WakaTime resources.
• Rate-limits reads per file (once per 2 minutes), sends saves immediately, and force-flushes on shutdown.
• Fails open: WakaTime errors never break OMP tool calls.
• Adds --sync-ai-disabled; prompt and tool output are never sent as heartbeat data.

Install from GitHub

git clone https://github.com/VxxxlBxxxxv/omp-wakatime.git
cd omp-wakatime
npm install
npm run build
omp install .

For a one-session smoke test without installing:

omp -e ./dist/index.js

After an npm release exists, the package-name form should be:

omp install omp-wakatime

Configure WakaTime

Create ~/.wakatime.cfg:

[settings]
api_key = waka_your_api_key_here

Optional debug logging:

[settings]
debug = true

Logs are written to:

~/.wakatime/omp-wakatime.log

State is written to:

~/.wakatime/omp-wakatime-state/
~/.wakatime/omp-wakatime-cli-state.json

If $WAKATIME_HOME is set, resources live under that directory and config is read from $WAKATIME_HOME/.wakatime.cfg.

What is sent to WakaTime

Session heartbeat:

wakatime-cli \
  --entity <project>/.omp-session \
  --entity-type file \
  --project-folder <project> \
  --plugin "oh-my-pi/<version> omp-wakatime/<version>" \
  --sync-ai-disabled \
  --is-unsaved-entity \
  --category coding

File heartbeat:

wakatime-cli \
  --entity <absolute-file-path> \
  --entity-type file \
  --project-folder <project> \
  --plugin "oh-my-pi/<version> omp-wakatime/<version>" \
  --sync-ai-disabled \
  --category "ai coding" \
  --write \
  --ai-line-changes <net-lines>

Privacy boundary

Sent intentionally:

• project folder;
• file path/entity;
• category;
• plugin identifier;
• AI line-change count.

Not sent by this extension:

• prompt text;
• tool output;
• command output;
• file content;
• browser/page content.

WakaTime is a metadata SaaS. If project/file path metadata is sensitive, use a self-hosted WakaTime-compatible backend such as Wakapi or do not enable this extension.

Heartbeat cadence

The extension follows the official plugin guide rule, keyed per file: send a heartbeat when the file was saved, when it changed (first activity on a file), or when more than two minutes passed since that file's last heartbeat.

• each touched file is rate-limited on its own key, not behind a single project-wide timer;
• save/write events bypass the interval and send immediately, so a write heartbeat carries its real timestamp;
• a repeated read on the same file within two minutes is skipped (the next activity re-evaluates it);
• session shutdown force-flushes everything still pending.

An agent runtime produces many tool events per session; wakatime-cli deduplicates on its side, so the per-file interval keeps traffic reasonable without coarsening save timestamps.

Troubleshooting

• No time shows up in WakaTime. Check the API key: ~/.wakatime.cfg must contain [settings] / api_key = ... (key from https://wakatime.com/api-key), or set WAKATIME_API_KEY. A missing key is reported once at startup in the extension log.
• Extension log: ~/.wakatime/omp-wakatime.log (respects $WAKATIME_HOME). wakatime-cli writes its own log to ~/.wakatime/wakatime.log.
• Debug mode: set debug = true in ~/.wakatime.cfg or export OMP_WAKATIME_DEBUG=1. This also passes --verbose to wakatime-cli.
• Old global wakatime-cli. If a wakatime-cli on PATH lacks the AI heartbeat flags (--sync-ai-disabled, --ai-line-changes), the extension ignores it and uses its bundled CLI; look for "Global wakatime-cli is too old" in the log.
• Verify ingestion: your activity should appear as editor "omp" on the WakaTime dashboard (WakaTime may capitalize it as "Omp"), or query the User Agents API.

Development

npm install
npm test
npm run typecheck
npm run build

Credits

Architecture references:

• @chronova/pi-plugin — OMP-native heartbeat scaffold.
• pi-wakatime — Pi WakaTime heartbeat semantics.
• opencode-wakatime — WakaTime CLI management and AI coding metrics patterns.

Contract

IWE IntegrationGate references: DP.SC.182 and DP.ROLE.071.

License

MIT