Hackatime

A minimalist, self-hosted WakaTime-compatible backend for coding statistics.

Forked from muety/wakapi for a Hackclub specifc version. Huge thanks to @muety for all the work he has done in wakapi which allowed us to spin this up so quickly :)

⌨️ How to use?

💻 Client setup

Hackatime relies on the open-source WakaTime client tools. In order to collect
statistics for Hackatime, you need to set them up.

Set up WakaTime for your specific IDE or editor. Please refer to the
respective plugin guide
Edit your local ~/.wakatime.cfg file as follows.

[settings]

Your Hackatime server URL

api_url = http://localhost:3000/api

Your Hackatime API key (get it from the web interface after having created an account)

api_key = 406fe41f-6d69-4183-a4cc-121e0c524c2b

Optionally, you can set up a client-side proxy
in addition.

🛠️ Server Setup

Clone the repo run go build and then ./hackatime -config config.yml. More info available in DOCS.md.

🔧 API endpoints

See our Swagger API Documentation.

For signing up user programaticaly you can use the /signup endpoint with the admin token as Bearer and it will return a json object similar to the following:

const signup = await fetch('http://localhost:8888/signup', {
method: 'POST',
headers: {
'Authorization': 'Bearer blahaji_rulz_da_world'
},
body: new URLSearchParams({
'location': 'America/New_York',
'captcha_id': '',
'invite_code': '',
'username': 'test',
'email': 'test@test.com',
'password': '123456',
'password_repeat': '123456'
})
});

console.log(await signup.json())

{"created":false,"api_key":"f91e9ae9-e667-44a6-bb1e-b40117e04439"}

If the user already exists then you will get a true value in the created field.

WakaTime integration

Hackatime plays well together with WakaTime. For one thing, you can forward heartbeats from
Hackatime to WakaTime to effectively use both services simultaneously. In addition, there is the option to **import
historic data** from WakaTime for consistency between both services. Both features can be enabled in the Integrations
section of your Hackatime instance's settings page.

GitHub Readme Stats integrations

Hackatime also integrates
with GitHub Readme Stats to generate fancy
cards for you. Here is an example. To use this, don't forget to enable public data
under Settings -> Permissions.

Click to view code

Github Readme Metrics integration

There is a WakaTime plugin for
GitHub Metrics that is also compatible with Hackatime. To use this, don't forget
to enable public data under Settings -> Permissions.

Preview:

Click to view code

uses: lowlighter/metrics@latest
with:
# ... other options
plugin_wakatime: yes
plugin_wakatime_token: ${{ secrets.WAKATIME_TOKEN }} # Required
plugin_wakatime_days: 7 # Display last week stats
plugin_wakatime_sections: time, projects, projects-graphs # Display time and projects sections, along with projects graphs
plugin_wakatime_limit: 4 # Show 4 entries per graph
plugin_wakatime_url: http://waka.hackclub.com # Wakatime url endpoint
plugin_wakatime_user: .user.login # User

Browser Plugin (Chrome & Firefox)

The browser-wakatime plugin enables you to track your web surfing in
WakaTime (and Hackatime, of course). Visited websites will appear as "files" in the summary. Follow these instructions to
get started:

Install the browser extension from the official
store (Firefox, Chrome)
Open the extension settings dialog
Configure it like so (see screenshot below):
- API Key: Your personal API key (get it at waka.hackclub.com)
- Logging Type: Only the domain
- API URL: https://waka.hackclub.com/api/compat/wakatime/v1 (alternatively, replace waka.hackclub.com with your self-hosted
  instance hostname)
Save
Start browsing!

Note: the plugin will only sync heartbeats once in a while, so it might take some time for them to appear on Hackatime.
To "force" it to sync, simply bring up the plugin main dialog.

Gnome Extension

If you're using the GNOME desktop, there is a quick way to display your today's coding statistics in the status bar.

Simply install the Executor extension and add the following
command as a status bar indicator:

~/.wakatime/wakatime-cli-linux-amd64 --today

❔ FAQs

Since Hackatime heavily relies on the concepts provided by WakaTime, their FAQs largely apply
to Hackatime as well. You might find answers there.

What data are sent to Hackatime?

File names
Project names
Editor names
Your computer's host name
Timestamps for every action you take in your editor
...

See the related WakaTime FAQ section for details.

What happens if I'm offline?

All data are cached locally on your machine and sent in batches once you're online again.

How does Hackatime compare to WakaTime?

Hackatime is a small subset of WakaTime and has a lot less features. Cool WakaTime features, that are missing in Hackatime, include:

Personal (non global) Leaderboards
Embeddable Charts
Personal Goals
Team / Organization Support
Additional Integrations (with GitLab, etc.)
Richer API

WakaTime is worth the price. However, this is made to be open source and free!!!

How are durations calculated?

Inferring a measure for your coding time from heartbeats works a bit differently than in WakaTime. While WakaTime
has timeout intervals, Hackatime essentially just pads every heartbeat that
occurs after a longer pause with 2 extra minutes.

Here is an example (circles are heartbeats):

|---o---o--------------o---o---|
| |10s| 3m |10s| |

It is unclear how to handle the three minutes in between. Did the developer do a 3-minute break, or were just no
heartbeats being sent, e.g. because the developer was staring at the screen trying to find a solution, but not actually
typing code?

WakaTime (with 5 min timeout): 3 min 20 sec
WakaTime (with 2 min timeout): 20 sec
Hackatime: 10 sec + 2 min + 10 sec = 2 min 20 sec

Hackatime adds a "padding" of two minutes before the third heartbeat. This is why total times will slightly vary between
Hackatime and WakaTime.

🙏 Thanks

Thanks a ton to muety/wakapi for making this project and for making it opensource and under a permissable license!

📓 License

MIT @ Kieran Klukas