WakaTime time tracking integration for Zotero. Automatically sends heartbeats while you read, annotate, and manage references so your research time appears on your WakaTime dashboard.
Note: This plugin is in early beta. Please report any issues or feedback when using it.
| Dependency | Required version |
|---|---|
| Zotero | 7.x |
| wakatime-cli | latest (auto-detected from ~/.wakatime/) |
Zotero 6 and earlier are not supported.
| OS | Architectures | Status |
|---|---|---|
| Windows | x86-64, arm64 | Supported |
| macOS | x86-64, arm64 | Supported |
| Linux | x86-64, arm64, arm | Supported, but not tested |
- Download the latest
.xpifile from the Releases page. - In Zotero, open Tools → Add-ons.
- Click the gear icon (⚙) → Install Add-on From File… and select the
.xpifile. Or just drag and drop the.xpionto the Add-ons page. Then it should install and activate immediately.
Prerequisites: Node.js ≥ 18 and npm.
git clone https://github.com/Rosayxy/zotero-wakatime.git
cd zotero-wakatime
npm install
npm run buildThis produces the zotero-waka-time.xpi file in .scaffold/build/. This is the Add-on package you can install in Zotero.
The plugin delegates all API communication to the official wakatime-cli binary. Place the appropriate binary for your platform under ~/.wakatime/:
~/.wakatime/wakatime-cli-linux-amd64 # Linux x86-64
~/.wakatime/wakatime-cli-linux-arm64 # Linux arm64
~/.wakatime/wakatime-cli-darwin-amd64 # macOS Intel
~/.wakatime/wakatime-cli-darwin-arm64 # macOS Apple Silicon
~/.wakatime/wakatime-cli-windows-amd64.exe # Windows x86-64
~/.wakatime/wakatime-cli-windows-arm64.exe # Windows arm64
The easiest way to get the binary is to install any other WakaTime plugin (e.g., the VS Code extension) which will download it automatically.
On first launch Zotero will prompt you for your WakaTime API key. You can also set or update it at any time in Zotero → Settings → WakaTime. The key is stored in ~/.wakatime.cfg (the standard WakaTime config file shared with other editors).
The plugin sends a heartbeat to WakaTime whenever you:
- Select a library item — the item's title becomes the entity; its first collection (or library name) becomes the project.
- Open a PDF or EPUB in the reader — sends a heartbeat immediately on open.
- Interact with the PDF/EPUB reader (click, scroll, keyboard) — throttled to at most one heartbeat every 2 seconds.
- Add or annotate an item (highlight, note, tag, metadata edit) — recorded as a write heartbeat.
Open Zotero → Settings → WakaTime to configure:
| Setting | Description |
|---|---|
| Enable WakaTime time tracking | Master on/off switch |
| API Key | Your WakaTime secret API key |
| Default Category | WakaTime category reported for each heartbeat (researching, learning, writing docs, browsing) |
| Enable debug logging | Writes verbose logs to ~/.wakatime/zotero-wakatime.log and Zotero's debug console |
- Make sure the plugin is enabled (Settings → WakaTime → Enable WakaTime time tracking).
- Verify the wakatime-cli binary exists and is executable:
~/.wakatime/wakatime-cli-linux-amd64 --version # adjust for your platform
- Check that your API key is correct at https://wakatime.com/settings/account.
- Ensure the binary name matches the pattern
wakatime-cli-{platform}-{arch}[.exe]exactly (all lowercase). - On macOS/Linux, confirm the binary is executable:
chmod +x ~/.wakatime/wakatime-cli-*. - Enable debug logging and check
~/.wakatime/zotero-wakatime.logfor errors when the plugin tries to send a heartbeat. Also check the Zotero debug console (Help → Debug Output Logging) for related messages.
Turn on Enable debug logging in preferences. Heartbeat attempts and CLI exit codes are written to:
~/.wakatime/zotero-wakatime.log- Zotero's built-in debug console (Help → Debug Output Logging)
Please open an issue at https://github.com/Rosayxy/zotero-wakatime/issues and include:
- Zotero version (
Help → About Zotero) - Operating system and architecture
- Contents of
~/.wakatime/zotero-wakatime.log(with debug logging enabled)