# vscode-wakatime turns editor activity into a coding time report

> vscode-wakatime is a BSD-3-Clause VS Code extension that sends heartbeats about your editing activity to a WakaTime dashboard, so the time report is derived from the editor rather than from a timer you have to remember. It suits developers who already use VS Code and accept that the activity data leaves the machine.

**wakatime/vscode-wakatime** — Visual Studio Code plugin for automatic time tracking and metrics generated from your programming activity.

- Repository: https://github.com/wakatime/vscode-wakatime
- Website: https://wakatime.com/vs-code
- Stars: 1,509 · Forks: 217
- Language: TypeScript
- License: BSD-3-Clause
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/wakatime-vscode-wakatime

## A time report derived from the editor, not from a timer

The problem vscode-wakatime addresses is the least liked part of productivity work: remembering what you did all day. Most time trackers ask you to start and stop a timer, and the timer drifts out of sync with reality the moment a meeting interrupts you. This extension takes a different route. It watches what VS Code is doing, sends that activity to a dashboard, and derives the metrics and the time totals from it.

The audience is a developer who already lives in VS Code and wants the report without changing workflow. The package description is explicit that the metrics, insights and time tracking are generated automatically from programming activity. The plugin is listed in the marketplace as WakaTime, published by WakaTime, under the identifier WakaTime.vscode-wakatime.

The implementation is TypeScript, packaged with webpack into two bundles, one for the desktop extension host and one for the web, since the manifest declares both a main entry point of ./dist/extension and a browser entry point of ./dist/web/extension. It is BSD-3-Clause licensed, the version in the manifest is 30.2.1, and it declares compatibility with VS Code from 1.89.0 upwards. The last push to the repository was on 2026-07-15, and the project publishes through the marketplace rather than through GitHub releases, which is why the repository itself has no tagged releases.

## A thin extension over wakatime-cli and a config file

The extension is not the whole product. The documentation points repeatedly at wakatime-cli, and the file layout gives it away. The configuration is an INI file at $HOME/.wakatime.cfg, and the documentation describes it as holding the extension settings, with more detail available in the wakatime-cli configuration reference. Errors that fall outside the scope of the extension are written to $HOME/.wakatime/wakatime.log, which the troubleshooting notes attribute to wakatime-cli rather than to the plugin.

There is a second file, and it is worth knowing about. When a heartbeat cannot be sent, the error message contains the phrase about not sending a heartbeat due to backoff, and the documented fix is to delete the ~/.wakatime/wakatime-internal.cfg file to trigger an API connection and surface the real error. That is the shape of a client with a retry policy and a backoff state file, which is the practical answer to how the reporting behaves when the network is unavailable.

The extension itself does a small amount of work around that client. It registers commands in the command palette, it shows a status bar item, and it exposes VS Code specific settings. The manifest shows it activating on every event, with activationEvents set to a single wildcard, and its extensionKind set to workspace, which is what decides where it runs when you connect to a remote host.

## Installing from the marketplace and entering the api key

Installation runs inside VS Code rather than from a package manager. The command palette is the entry point: press F1, or the macOS equivalent, and type install, then pick Extensions: Install Extension. After that you type wakatime and press enter, and the extension is installed from the marketplace.

The third step is the one that matters for whether anything gets reported. You enter your api key when prompted, and if no prompt appears you can bring it up yourself by typing WakaTime API Key in the same palette. The key is linked from the api key page on the project's own site. Once the key is in place, your coding activity shows up on the WakaTime dashboard, and the usage section of the documentation simply points you there to see it.

There is one environment variable path worth knowing. If you use an online IDE such as gitpod, the documentation says to add the api key to the global environment variable WAKATIME_API_KEY instead. That matters for the remote case in the troubleshooting section, where a shared server means the key has to exist where the extension actually runs.

## Status bar placement that only changes after a restart

The VS Code specific settings are grouped under wakatime in the settings UI, and two of them control where the status bar item sits. wakatime.align takes left or right and decides which side of the status bar shows the WakaTime item, and wakatime.alignPriority takes a number that controls the order, with higher values appearing more to the left. Both settings require restarting VS Code before they take effect, which is a small annoyance that comes from the item being created once when the extension activates.

A third setting hides today's coding activity from the status bar entirely. The documented way to do that is to open the command palette and set WakaTime: Status Bar Coding Activity to false. Turning off the visible counter does not stop the reporting, it only removes the indicator, so a team that wants the data but not the distraction can use that setting without changing anything else.

There is also a kill switch. To disable the extension at startup you add disabled=true to the config, and the same thing can be done from the palette by selecting WakaTime: Disable. Since the config file is shared by other WakaTime plugins, the two mechanisms interact with the rest of the suite rather than with VS Code alone.

## Debugging a plugin that reports nothing

When the dashboard shows no activity, the documented path starts with a debug switch. You open the palette with F1, type WakaTime: Debug, press enter and select true. That turns on debug mode inside the client, and the next step is to open the developer console with Help and Toggle Developer Tools to watch the logs and errors as you work.

Two more locations matter. Errors outside the scope of the extension land in $HOME/.wakatime/wakatime.log, and the backoff case has its own fix, deleting ~/.wakatime/wakatime-internal.cfg so that a real API connection is attempted and the actual error message becomes visible instead of a retry notice. A third resource is external to the editor: the How to Debug Plugins guide explains how to check when coding activity was last received from your editor, using the plugin status page.

One case is specific to corporate networks on Microsoft Windows. Behind a corporate proxy, the documentation suggests enabling the Windows root certificates inside VS Code with the win-ca extension, installed from the extensions view. Without that trust store in place, a proxy that re-signs traffic produces a connection failure that looks like a plugin bug.

## Running from source, and the remote host question

Working on the extension itself is a documented flow. You clone the repository, install the dependencies with npm, and start the webpack watcher:

```bash
git clone git@github.com:wakatime/vscode-wakatime.git
cd vscode-wakatime
npm install
npm run watch
```

The last step is unusual and worth spelling out. You install the extension from the marketplace as usual, then replace the installed copy with your local build by symlinking the marketplace directory to your own build output, so the extension directory contains a link to ./dist/extension.js. There is a second path for the web build, which compiles without the production webpack mode and then opens a browser-based test host:

```bash
npm run compile
npm run open-in-browser
```

That lands you on localhost:3000 in a browser.

The remote host question is separate and matters more in practice. When you connect to a remote host with the SSH extension, the documentation suggests forcing WakaTime to run locally rather than on the server, and it says the configuration is needed when the server is shared among other people. The reason is visible in the manifest, where extensionKind is set to workspace, which places the extension on the remote side by default. A shared server with your api key and your editing history would be visible to the other users of that machine, so forcing local execution is the safer arrangement.

## Where a manual timer fits better

The alternative approach is the timer: you start a stopwatch when you begin a task and stop it when you finish, and the report is a list of intervals you typed yourself. The difference in approach is what the data is. A timer measures your estimate of a session, and it is wrong whenever you forget to start or stop. An editor-derived report measures the actions that happened, and it is wrong whenever the activity does not map neatly onto the work, since reading documentation and reviewing a diff both look like typing.

That is the trade to weigh. The automatic approach needs no discipline from you and produces a daily total without any input, but the unit it measures is keystrokes and file events, not attention. The manual approach needs effort and produces intervals with human meaning. For a developer whose day is mostly writing code, the automatic route is more accurate. For someone whose work is reading, reviewing and discussing, a timer with a few named projects attached will describe the day better than a file-event log.

A third option is to keep the extension but ignore the dashboard, using it as a local record rather than a report. Nothing in the documentation requires you to look at the dashboard, and the same wakatime-cli configuration can point at a different endpoint, though the documentation in this repository covers only the hosted dashboard and does not describe a self-hosted setup.

On maintenance, the project is BSD-3-Clause licensed with the text in the LICENSE file, it keeps a CHANGELOG.md and an AUTHORS file, and the repository carries a tslint.json, a .prettierrc and a webpack.config.js. There are no GitHub releases, because the versioning happens on the marketplace, and the manifest version of 30.2.1 is the number to quote when you report a problem.

## Conclusion

vscode-wakatime fits developers who want a time report derived from what they actually typed, and who are willing to send that activity to a hosted dashboard. It does not fit a team that cannot send editing metadata off the machine, or a person who wants a timer they control. Verify first that your api key is present in $HOME/.wakatime.cfg, that the WakaTime: Debug command shows a heartbeat, and that your organisation is comfortable with the contents of the $HOME/.wakatime directory before you rely on the numbers.

## FAQ

### How do I install WakaTime for VS Code?

Press F1 or the macOS equivalent, type install and pick Extensions: Install Extension, then type wakatime and press enter. When the extension asks for your api key, enter it, and if you are not prompted you can bring the prompt up by typing WakaTime API Key in the same palette.

### Where does vscode-wakatime store its settings?

Extension settings are stored in the INI file at $HOME/.wakatime.cfg. A second file, ~/.wakatime/wakatime-internal.cfg, holds internal state, and deleting it is the documented fix when the plugin reports that it will not send a heartbeat due to backoff.

### How do I hide the WakaTime counter in the VS Code status bar?

Open the command palette and set WakaTime: Status Bar Coding Activity to false. The related settings wakatime.align and wakatime.alignPriority control which side of the status bar the item appears on and its order, and both need a VS Code restart to apply.

### What should I check when WakaTime shows no activity in VS Code?

Enable debug mode with WakaTime: Debug set to true, then watch the developer console opened from Help and Toggle Developer Tools. Errors outside the extension are logged to $HOME/.wakatime/wakatime.log, and on Windows behind a corporate proxy the documentation suggests installing the win-ca extension so VS Code trusts the root certificates.

### Does vscode-wakatime run on a remote SSH host?

The extension declares extensionKind as workspace, so it runs on the remote side by default. The documentation suggests forcing WakaTime to run locally instead, which matters when the remote server is shared among other people.

## Sources

- [Issues](https://github.com/wakatime/vscode-wakatime/issues)
- [License: BSD-3-Clause](https://github.com/wakatime/vscode-wakatime/blob/master/LICENSE)
- [Project website](https://wakatime.com/vs-code)
- [README](https://github.com/wakatime/vscode-wakatime/blob/master/README.md)
- [wakatime/vscode-wakatime on GitHub](https://github.com/wakatime/vscode-wakatime)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/wakatime-vscode-wakatime