vim-wakatime: time tracking generated from your editing

A plugin that reports what you typed

WakaTime is an open source Vim plugin for metrics, insights and time tracking automatically generated from your programming activity.

The mechanism is worth understanding at the start, because it decides where the complexity lives. The vim-wakatime plugin automatically downloads and updates wakatime-cli in your $WAKATIME_HOME/.wakatime/ folder, and WakaTime plugins also share a common $WAKATIME_HOME/.wakatime.cfg config file, with $WAKATIME_HOME defaulting to your $HOME folder.

So the Vim plugin is a front end. It watches the editor for the events that indicate work, files them, and hands them to a command line client that owns the network protocol, the offline queue and the configuration. That split is why the plugin is small, why the same configuration works across editors, and why a problem with your tracking is usually a problem with the CLI.

The supported editors are listed in the badges at the top of the README, and they are Vim, Neovim, MacVim and gVim. The primary language in the repository listing is Lua, and the licence is BSD-3-Clause, which is a permissive licence and a contrast with the hosted service it feeds.

The home page is wakatime.com/vim, and the project is not archived, with the last push on 2026-08-10.

Six ways to install it, and the first-run key

The installation section is the longest part of the README, because there are six supported plugin managers and each has its own convention.

With Vundle it is a line appended to your.vimrc followed by vim +PluginInstall. With Pathogen you clone the repository into ~/.vim/bundle. With vim-plug you add the Plug line to.vimrc, reload it with:so ~/.vimrc or restart Vim, and run:PlugInstall. With Packer you add the use line to your plugins file. With plain Vim 8 and later, you create ~/.vim/pack/plugins/start and clone the repository into it. And with Lazy.nvim you add an entry to your plugins file:

{ 'wakatime/vim-wakatime', lazy = false }

After the install you restart Vim, and if this is the first WakaTime plugin on your machine you type:WakaTimeApiKey inside Vim, enter your API key and press enter. Your coding activity then shows up on your WakaTime dashboard.

The Lazy.nvim entry sets lazy = false, so the plugin is not deferred: a time tracker that only starts counting when you open a file would miss most of your work.

There is also a documented option to turn off the lualine status bar item, which is what people want when the tracker takes over a piece of their status line:

{ 'wakatime/vim-wakatime', lazy = false, opts = { status_bar_enabled = false } }

The commands, and the ones that only exist for old Vim

The command list is short, and two of the entries are labelled for a specific version.

:WakaTimeApiKey sets or changes the API key saved in your ~/.wakatime.cfg.:WakaTimeToday echoes your total coding activity for today, which is a quick way to see whether the tracker is working without opening a browser.

Then there are the debug commands.:WakaTimeDebugEnable enables debug mode, and the documentation notes that it may slow down Vim so you should disable it when finished, and:WakaTimeDebugDisable turns it off.

The last three are the screen redraw commands, and two of them carry the qualifier only for Vim below 8.0::WakaTimeScreenRedrawEnable to enable screen redraw to prevent artifacts,:WakaTimeScreenRedrawEnableAuto to redraw the screen when the plugin takes too long, and:WakaTimeScreenRedrawDisable to disable screen redraw.

That set exists for a specific historical problem. On older Vim versions, a plugin that blocks briefly while it does its work can leave the screen visually corrupted, because the redraw does not happen at the right moment. The fix is to force a redraw, and the automatic variant does it only when the plugin has taken long enough that the user would notice.

On a current Vim or Neovim these commands are largely irrelevant, which is why they carry the version qualifier, and it is a small example of a plugin carrying compatibility code for editors that are years old.

Debugging, and the synchronous mode that makes Vim slow

The troubleshooting section is the most practically useful part of the README, and it starts with the command to run and the log to tail.

Run :WakaTimeDebugEnable in Vim, then run this Terminal command:

`tail -f ~/.wakatime/wakatime.log`

Enabling debug mode writes Vim Script errors to your Vim status bar and tells wakatime-cli to write verbose logs to $WAKATIME_HOME/.wakatime/wakatime.log.

The advice that follows is the part people miss. Debug mode can make it hard to find the real error because of all the extra logging, so you should also try disabling debug mode while tailing the log and editing files in Vim. The idea is to isolate the two sources: the log shows you what the CLI received, and turning debug mode off removes the noise from the editor side.

There is a second behaviour change to be aware of. With debug mode enabled, the plugin sends data synchronously, so you disable it when finished debugging with :WakaTimeDebugDisable. That is the reason for the earlier warning that debug mode may slow down Vim: the plugin is blocking on the send instead of queueing it in the background, and a slow network makes your editor feel slow.

The README also links a How to Debug Plugins guide for checking when coding activity was last received from Vim through the User Agents API, and points at the wakatime-cli troubleshooting section for anything more general.

Uninstalling, and the shared config file

The uninstall instructions are three steps, and the middle one is the one people miss.

Remove the plugin line from your .vimrc, run rm ~/.wakatime.* in a terminal, and then run vim +PluginClean.

That middle step matters because the plugin's state is not only in the plugin directory. The API key lives in ~/.wakatime.cfg, the downloaded CLI binary lives in ~/.wakatime/, and the log lives alongside it. Removing the plugin from your configuration leaves all of that behind, and the glob catches it in one command.

For vim-plug users the sequence is slightly different, because PlugClean needs to know the plugin is gone first. While in Vim you delete or comment out the Plug command from your .vimrc, reload it with :so ~/.vimrc or restart Vim, and then run :PlugClean, which detects and removes undeclared plugins.

The shared configuration file is worth understanding for a different reason. Because the config lives in $WAKATIME_HOME/.wakatime.cfg and $WAKATIME_HOME defaults to your home directory, a second WakaTime plugin, for another editor, will pick up the same API key without you entering it again. That is convenient, and it is also a reason to be careful about what you install on a machine, since anything that can read that file has your key.

The repository and the release line

The repository is small, and the directory layout shows a mature Vim plugin rather than an application.

There is a lua/ directory for the plugin logic in the current Vimscript alternative style, a plugin/ directory for the Vim script entry points that older Vim versions need, a doc/ directory for the help file, and scripts/ for helper scripts. There is a .stylua.toml, which is the configuration for StyLua, the Lua formatter, and that alone tells you the Lua code is formatted with a tool rather than by hand.

The repository also carries AUTHORS, a HISTORY.rst changelog, and a LICENSE.txt with the BSD-3-Clause terms. The .gitignore is there because the plugin's working state, including the downloaded CLI, lives in the home directory rather than in the checkout, so there is nothing much to ignore in the tree itself.

The release history is small and spaced out. Version 11.2.0 came on 2024-09-17, 11.3.0 on 2024-11-15, and 12.0.0 on 2026-04-13, with the last push on 2026-08-10.

A major version bump after a long quiet period is a normal rhythm for a plugin like this, since the work is driven by whatever changes in the editors, in Vimscript, in the CLI or in the API. The relevant question for a user is not the version number but whether the plugin still matches your editor, and the compatibility with Vim 8 and later, with Neovim, MacVim and gVim, is the claim to check.

Editorial conclusion

Adopt vim-wakatime if you want per-project time tracking from the editor you already use, and if you are comfortable with a plugin that installs and updates a separate binary on your machine. Do not adopt it if you need the tracking to stay entirely inside the editor, because the plugin depends on an external executable, and check the privacy implications of sending your editing activity to a hosted service before you enable it. Before you start, set the API key with the WakaTimeApiKey command, keep the shared config file in mind if you use more than one WakaTime plugin, and read the debugging section, because the debug mode sends data synchronously and will make Vim feel slow while it is on.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. README
4. Releases
5. wakatime/vim-wakatime on GitHub