Getting started

Three pieces have to be in place before the first heartbeat: an editor AtoAxis can hear from, the CLI that actually delivers heartbeats, and a key that identifies your account. During Early Access, keys are issued to people on the list rather than at signup.

• VS Code 1.90 or newer for the first-party extension, or any editor that already has a WakaTime plugin
• wakaclock-cli on your PATH, or an absolute path in the wakaclock.cliPath setting: the extension buffers activity but never contacts the server itself
• An AtoAxis account plus an API key generated from the dashboard
• Outbound HTTPS. Heartbeats that cannot be delivered are queued locally in ~/.wakaclock/queue.db and resent later, so a flight or a dropped VPN does not lose the day

The API key authenticates every heartbeat your machines send. One key covers every editor and every AI hook on that account.

• Open Settings in the dashboard and find the API key panel
• Choose Generate key
• Copy the key. The dashboard keeps displaying it, so there is never a reason to regenerate just to read it again
• Regenerating replaces the old key immediately, so every machine still using the old one stops being accepted

wakaclock-cli config set-key YOUR_API_KEY

That writes the key into ~/.wakaclock/config.toml, which is also where the CLI keeps user_id and server_url. The VS Code extension stores its own copy in VS Code secret storage instead of settings.json, so the key is never committed with your editor config.

VS Code, the first-party extension

Extensions: install "AtoAxis — Developer Time Tracking"
Command Palette: Wakaclock: Set API Key
Command Palette: Wakaclock: Configure CLI Path   # only if the binary is not on PATH

Nothing else is required: typing updates an in-memory buffer, saving flushes it as a write, and switching files flushes the file you left.

Any other editor, over the WakaTime protocol

[settings]
api_url = https://api.atoaxis.com/api/v1
api_key = your_generated_api_key

An editor that already has a WakaTime plugin needs only this file changed. There is no AtoAxis extension to install for it: AtoAxis implements the WakaTime heartbeat API, so the plugin keeps working exactly as before.

Two commands answer "is it actually working?". The first asks the server, the second asks for the total it has counted today. Neither reads your local files.

wakaclock-cli status   # server reachable, API key present
wakaclock-cli today    # today’s total, as the server counts it

• The VS Code status bar shows the same total and refreshes every 15 seconds
• Wakaclock: Send Heartbeat Now flushes buffered activity immediately instead of waiting for the 120-second same-file cadence
• The dashboard Overview page shows the total once the first heartbeat has landed

Almost every first-run problem is one of these five, and each has a check that tells you which one it is.

• No total in the status bar: the CLI cannot be found. Run Wakaclock: Configure CLI Path, or set wakaclock.cliPath to the absolute path of the binary
• Reading code is not counted: only edits, saves and file switches produce heartbeats, and gaps at or beyond the idle timeout are excluded on purpose
• The total stopped rising: run wakaclock-cli status. Undelivered heartbeats sit in ~/.wakaclock/queue.db and are resent once the server is reachable again
• One project counted twice: two checkouts of the same repository are two project names until you merge them under Settings, with project rules or a manual merge
• AI work missing: run AtoAxis: Show AI Tracking Status, then AtoAxis: Set Up AI Tracking to register hooks for Claude Code, Codex CLI or Gemini CLI. Cursor and Copilot have no adapter yet