wakatime-zsh-plugin

February 28, 2026 ยท View on GitHub

wemake.services Build Status GitHub Release

What does this plugin do?

This plugin provides zsh and wakatime integration. In other words, it tracks all time you spend in a terminal. Unlike other plugins, this one tries to keep all your spent time in the same wakatime's project.

Info

Prerequisites

Before we start you will need to run:

python3 -c "$(wget -q -O - https://raw.githubusercontent.com/wakatime/vim-wakatime/master/scripts/install_cli.py)"

This command will install Wakatime's CLI.

Installation

antigen

If you're using antigen, you can install this plugin with antigen bundle sobolevn/wakatime-zsh-plugin.

zgen

If you're using zgen, add this plugin to your init.zsh with zgen load sobolevn/wakatime-zsh-plugin.

Manual

cd ~/.oh-my-zsh/custom/plugins && git clone https://github.com/sobolevn/wakatime-zsh-plugin.git wakatime

Then set wakatime to the plugins list inside your .zshrc.

Official plugin documentation

Configuration

Wakatime supports configuration via ~/.wakatime.cfg. You will need to set your api_key.

There are number of options to set via your environment variables:

  • $WAKATIME_DO_NOT_TRACK: you can also disable tracking for some period of time by setting WAKATIME_DO_NOT_TRACK=1. defaults to false
  • $WAKATIME_TIMEOUT: to limit the time to sync with the wakatime servers, defaults to 5 seconds
  • $WAKATIME_DISABLE_OFFLINE: to disable wakatime in offline mode, defaults to false
  • $ZSH_WAKATIME_BIN: set a custom path for the wakatime cli, defaults to wakatime

Project Detection

The plugin determines the project name using the following priority:

  1. .wakatime-project file in the current directory
  2. .wakatime-project file at the git repository root
  3. If inside a git repo but no .wakatime-project file is found, the --project flag is omitted so that wakatime-cli can auto-detect the project (e.g. from the git remote URL when project_from_git_remote is enabled in ~/.wakatime.cfg)
  4. If not inside a git repository, the project name defaults to Terminal

Alternatives

There are several alternatives to this project:

  1. zsh-wakatime
  2. bash-wakatime
  3. fish-wakatime

See the full list here.

License

MIT. See LICENSE for more details.