WakaTime’s open source plugins only track when you’re typing in your editor. Stop typing longer than your keystroke timeout preference, and the WakaTime plugin stops tracking your stats.
WakaTime is accurate to 1 microsecond (0.000001 seconds), but the plugins depend on you computer’s clock and operating system. On Windows, precision is only ±16 milliseconds (0.016 seconds).
To achieve this accuracy, WakaTime plugins send heartbeats from your editor when the file you’re typing in changes, when you save a file, and every 2 mins of typing in the same file. Heartbeats are joined into durations based on your timeout preference, then displayed on your dashboard.
For contractors, you might want to increase your timeout preference to capture all your billable hours. More info in this blog post.
Your keystroke timeout preference is the maximum time allowed between durations when calculating your total coding activity for a day. Think of it like a granularity setting. It can’t make you code more or less, it just combines durations with more or less accuracy.
For ex, if you typed code for 2 mins, took a 13 min break, then typed code for 1 min:
A visual example of the affect on accuracy of durations:
Note: Public profiles, leaderboards, and public badges always use the default 15 minute keystroke timeout. Private project badges, embedded charts, goals, insights, invoices, and your personal dashboard use your personal keystroke timeout preference.
When working offline with supported editors* your coding activity is saved in a boltdb database at $HOME/.wakatime.bdb.
The next time you use your IDE when online, your coding activity is synchronized to your WakaTime dashboard.
* All editor plugins using the wakatime-cli have support for offline coding. The Chrome extension supports working offline using IndexedDB. The Brackets extension does not support working offline.
Daily average is the number of hours you coded on average each day. It can be seen on your personal dashboard, private leaderboards, and if you make your coding activity public also on your public profile and public leaderboard.
The formula for daily average is:
Daily Average = Hours / Days
Where:
Hours is the sum of the total number of hours you coded in the last seven days.
Days is the number of days you coded at least one minute in the last seven days.
This means daily average skips weekends or days where you didn’t code!
For example: If you wrote some code for 2 hours on Monday and 4 hours on Tuesday last week, your daily average would be (2 + 4) / 2 = 3 hours.
Also, leaderboards and public profiles use a slightly different formula than your personal dashboard.
Leaderboards and profiles calculate daily average over the last seven days starting from yesterday, while your personal dashboard calculates daily average from today.
Your public profile uses the default 15 minute timeout value with a time range of the Last 7 Days from Yesterday.
We also subtract coding activity from language Other.
The leaderboards use the same formula as your public profile.
Setting your preferences to the defaults, matching the leaderboard time range, and subtracting coding activity categorized as language Other will show the same coding activity as your dashboard.
Leaderboards only update a few times per day, and always lag behind your public profile.
To see when your public profile last updated, check the modified_at field from the Stats API.
To see when a leaderboard last updated, check the modified_at field from the Leaders API.
Set a custom color for your project, otherwise the default is to use a random color when displaying your project on dashboards.
Using each IDE’s icon image, we’ve extracted a list of the most dominant colors for each IDE. We use these colors when displaying IDEs on WakaTime dashboards.
Based off GitHub’s language colors, we’ve built a list of colors for each language used on all WakaTime dashboards.
Using each operating system’s logo, we’ve defined colors for each os used on all WakaTime dashboards.
Here’s the list of colors for each category used on all WakaTime dashboards.
Most WakaTime plugins share a common config file, ~/.wakatime.cfg. Three settings are available to customize the WakaTime status bar inside your IDE. Here they are with their default values:
status_bar_enabled = true
status_bar_coding_activity = true
status_bar_hide_categories = false
By default, all categories are displayed in your status bar. For ex: 3 hrs coding, 42 mins compiling, 9 mins browsing. To only display the total time, your ~/.wakatime.cfg would look like:
[settings]
status_bar_hide_categories = true
Then, your status bar would display 3 hrs 51 mins without specifying coding, compiling, or browsing.
All WakaTime plugins are open source on GitHub.
WakaTime plugins send heartbeat events triggered from user actions inside your text editor to the WakaTime API.
Heartbeat events contain data such as:
* Only file paths are sent, not file contents.
** Websites are only sent if you install the WakaTime Browser extension.
Heartbeat events are sent:
Your file contents are never sent to WakaTime servers. Only the file paths, or the location of the files on your machine, are sent to WakaTime servers.
All WakaTime plugins are open source, so you’re protected by the eyes of the community.
If the file paths or project names are sensitive, you can tell WakaTime plugins to not send certain projects, files, folders, or obfuscate them before sending to WakaTime servers.
The config options for privacy are:
hide_project_folder - turns /Users/username/projects/flask/src/main.py into src/main.pyhide_project_names - turns flask into a random generated project name, for ex: AutumnTree43hide_branch_names - disables sending Git branch nameshide_file_names - turns /projects/flask/src/main.py into HIDDEN.py, and disables other metadata including line counts and dependencies usedexclude - prevents sending any data on folders where the path matches a list of regex patternsinclude - used in combination with exclude to only send an allowed list of folder paths, for ex: exclude .* then include a list of allowed foldersinclude_only_with_project_file - prevents sending any data on folders which don’t contain a .wakatime-project file in the project folderAdd the line:
hide_project_folder = true
to your in your ~/.wakatime.cfg file to send only relative paths to WakaTime servers.
For example, /Users/username/projects/flask/src/main.py would be sent relative to the project folder flask as src/main.py. When no Git project can be detected, only the file name is sent.
Use hide_file_names with a list of folders in your ~/.wakatime.cfg file.
Any files inside those folders will be replaced with HIDDEN.ext before they leave your computer, where ext is the original extension of the file.
For ex:
hide_file_names =
/Users/username/private/
/Users/username/projects/[\d+]/
Will change /Users/username/private/secret_project/main.py and /Users/username/projects/1337/src/main.py into HIDDEN.py before sending to WakaTime servers.
Note: That means time spent in those two files will be combined and displayed as one file on your dashboard.
Note: To obfuscate all files in all folders, use hide_file_names = true.
Note: Sublime Text users won’t have a ~/.wakatime.cfg file, so create one using this example config.
After obfuscating, delete any past coding activity using the Coding Activity Delete Tool.
Use hide_project_names with a list of folders in your ~/.wakatime.cfg file.
Any files inside those folders will have their project names replaced with a random string, for ex:
[settings]
hide_project_names =
/Users/username/private/
/Users/username/projects/[\d+]/
With a Git project at /Users/username/private/secret_project/, will create a .wakatime-project file at /Users/username/private/secret_project/.wakatime-project that overrides your secret_project project name with a randomly generated name.
After obfuscating, rename the old project to merge it with the new random project name.
Note: To obfuscate all project names, use hide_project_names = true.
Note: Sublime Text users won’t have a ~/.wakatime.cfg file, so create one using this example config.
Your file contents are never sent to WakaTime servers. Only the file paths, or the location of the files on your machine, are sent to WakaTime servers.
However, sometimes even the names of your projects are sensitive.
To exclude folders from WakaTime,use exclude with a list of folders in your ~/.wakatime.cfg file.
[settings]
exclude =
/Users/username/private/
/Users/username/projects/[\d+]/
/Users/username/private/ is a regex, so any file path matching the regex is ignored by your WakaTime plugin.
Another way is exclude all folders, and only include those folders containing a `.wakatime-project` file in the project’s folder.
Add this line to your ~/.wakatime.cfg file:
include_only_with_project_file = true
Then run touch .wakatime-project inside each project you want to track. All other projects will be excluded from tracking.
After excluding folders, delete the project to remove it from your WakaTime dashboard.
Note: Use forward slash to separate folders, even on Windows.
Note: Sublime Text users won’t have a ~/.wakatime.cfg file, so create one using this example config.
Yes, you can export all your coding activity in JSON format from your account settings.
There are two export options: Heartbeats or Daily Totals.
Heartbeats are a raw dump of each timestamp ping we received when you were actively coding in your IDE, and is the same format we store your code stats to power all WakaTime dashboards.
The Daily Totals option is a sum of your total code time per day, expanded by project, file, language, etc. It’s what you see for each day’s data point on the charts from your dashboard, and great for doing analysis where you only need granularity per day.
However, for backing up your code stats or to analyze what time of day you were coding, you must select the Heartbeats export option.
Your coding activity is stored forever, even when using the Free plan. If you decide to upgrade to a paid plan* in the future, then your dashboard unlocks your historical coding activity.
* The Basic plan only adds additional features, but doesn’t unlock historical coding activity. The Premium plan and Team plans do unlock historical coding activity.
Yes, to delete a project click the delete project item on a project’s dashboard. Be careful, the project and all it’s code stats will be deleted permanently.
You can also delete coding activity for specific files using the Coding Activity Delete Tool.
To exclude projects in the future, add the project’s path to your $HOME/.wakatime.cfg file under the exclude setting.
Using custom rules you can delete all code stats of a specific category, in two stages.
For ex: To delete all stats with category Browsing, create a custom rule: If category equals Browsing, set project to Browsing For Deletion.
The project name doesn’t matter, as long as you don’t already have a project with that same name.
Then, finally delete that Browsing For Deletion project using the project dashboard dropdown menu.
Yes, when you delete your account we immediately delete your code stats from our production servers.
Following our Data Security Policy, we wait 27 days and then also delete your code stats from all backups.
It’s not possible to recover deleted code stats, so make sure to export your heartbeats before deleting your account.
WakaTime detects and creates projects for you automatically based on your coding activity.
You don’t manually create projects. Instead, use your IDE like normal and projects will appear on your WakaTime Dashboard.
By default, WakaTime uses your Git repo folder as the project name.
You can overwrite the project name using a wakatime-project file, project map config section, or custom rules.
For more info on project detection, and how to overwrite or customize project detection, see wakatime-cli usage.
To rename a project, click rename project from the dropdown on the project’s dashboard.
From your personal dashboard, click on a day in the chart to view the durations of time logged that day. Next, click on any file or time duration to edit the project, language, category, or branch.
As a last resort, use custom rules*:
* Warning: this will rename projects from past coding activity. Use with caution!
From your personal dashboard, click on a day in the chart to view the durations of time logged that day. Next, click on any file or time duration to edit the project, language, category, or branch.
WakaTime is an automatic time tracker, so you shouldn’t need to manually add time. WakaTime is very accurate, flexible, and editable.
If you’ve already tried changing your Keystroke Timeout and you still want to manually add time, connect a calendar integration.
Meetings from your calendar will be displayed on your dashboards.
Using custom rules you can even change the category from Meeting to Coding, or any other supported categories.
Currently, the calendar integrations are the only supported way to manually add time to your dashboard.
For Google Calendar events, the event title and description are matched against. Google Calendar events are stored as external durations, with the event’s title stored in the ExternalDuration.entity field and the event’s description stored in the ExternalDuration.meta field.
WakaTime plugins use the Chroma syntax highlighter for language detection. See the languages supported by Chroma, which is also the list of languages detected by WakaTime.
First, request support for your language.
Next, you can manually override language detection using custom rules and file extension matching:
Custom rules modify future and past coding activity, so they’re useful for correcting languages displayed wrong on your dashboard.
However, for fixing languages going forward please email us and we’ll improve language detection for everyone.
15 minutes keystroke timeout and subtracting Other language?Other language, and make sure it’s more than the last person on the last page of the leaderboard.You have several ways to control projects on your team dashboard:
Some reasons why your personal dashboard may show different time from your team dashboard:
| Variable | Description | Example |
|---|---|---|
{y} | Year with century. | 1999, … |
{yy} | Year without century. | 99, … |
{m} | Month, zero-padded. | 01, 02, …, 12 |
{mm} | Month. | 1, 2, …, 12 |
{mmm} | Month as 3 char string. | JAN, FEB, …, DEC |
{mmmm} | Month as string. | JANUARY, FEBRUARY, …, DECEMBER |
{d} | Day, zero-padded. | 01, 02, …, 31 |
{dd} | Day. | 1, 2, …, 31 |
{h} | Hour, 24-hour clock, zero-padded. | 00, 01, …, 23 |
{hh} | Hour, 24-hour clock. | 0, 1, …, 23 |
{hhh} | Hour, 12-hour clock, zero-padded. | 01, 02, …, 12 |
{hhhh} | Hour, 12-hour clock. | 1, 2, …, 12 |
{p} | AM or PM. | AM, PM |
{mn} | Minute, zero-padded. | 00, 01, …, 59 |
{mnn} | Minute. | 0, 1, …, 59 |
{s} | Second, zero-padded. | 00, 01, …, 59 |
{ss} | Second. | 0, 1, …, 59 |
{i}* | Invoice counter. | 1, 2, … |
{c}** | Invoice counter, per client. | 1, 2, … |
* Pad invoice counters with zeros by repeating the variable letter. For example, {iiii} will result in invoice number 0001.
** Invoice IDs must be unique. Make sure to add a client prefix to your Invoice ID Format when using {c}.
Make sure the plugin is correctly installed in your editor. ( Look for a WakaTime menu under File/Tools )
Check the plugin status page for when your editor was last seen, and if a new version is available. If your editor isn’t listed or hasn’t been seen in a while, first turn on debug mode then check for errors in your log files:
WakaTime Settings menu in the Tools or File menu of your IDE.:WakaTimeDebugEnabledebug option in your WakaTime.sublime-settingsWith debug mode on, check your IDE log file and your $HOME/.wakatime/wakatime.log file for error messages.
If your error message contains won't send heartbeat due to backoff then delete your $HOME/.wakatime/wakatime-internal.cfg file to trigger an API connection so we can see the real error message.
If you use multiple computers, find when a computer’s hostname was last heard from using the Machine Names API.
The value is the Hostname and ip is the IP Address of your machine.
To see your recent raw coding activity, use the Heartbeats API.
Please create a new issue in the appropriate GitHub repo with any error messages.
All WakaTime plugins share wakatime-cli for communicating with the API.
The wakatime-cli is located at ~/.wakatime/wakatime-cli and logs errors to $HOME/.wakatime/wakatime.log.
If your error message contains won't send heartbeat due to backoff then delete your $HOME/.wakatime/wakatime-internal.cfg file to trigger an API connection so we can see the real error message.
Errors from the editor plugin go to your IDE’s log file:
Please create a new issue in the appropriate GitHub repo with your error messages.
Your api key is a secret code used to link coding activity from your WakaTime plugin to your personal dashboard:
Your api key is available on your WakaTime Account Settings page.
To generate a new api key, click the refresh button .
After generating a new api key, remember to update your plugin settings with your new key:
File → WakaTime API Key or Tools → WakaTime Settings in most text editors:WakaTimeApiKey command in VimYour WakaTime config file is located in your user home folder ($HOME/~/%USERPROFILE) at ~/.wakatime.cfg.
Notice the filename starts with a dot, so it's considered a hidden dotfile.
The config file uses INI format.
WakaTime plugins share the same ~/.wakatime.cfg config file.
For available configs and default values, see this example config file.
Use this form to send a confirmation email to your inbox.
WakaTime plugins have a proxy config in ~/.wakatime.cfg, that should be set the same as your browser's proxy settings.
For example:
proxy = https://user:pass@host:port
SOCKS5 proxies are also supported:
socks5://user:pass@localhost:12345
NTLM LDAP proxies are also supported:
proxy = https://domain\user:pass@host:port
To use a custom CA Cert bundle file, add this line to your ~/.wakatime.cfg config file:
ssl_certs_file = /path/to/cafile.pem
To disable SSL Cert verification completely (dangerous) add line:
no_ssl_verify = true
Yes, all WakaTime plugins play well together. You can switch between multiple supported editors and your coding activity will be synchronized correctly. If you use revision control software, your project will be detected even when using multiple editors.