hackatime

README

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.

1. Set up WakaTime for your specific IDE or editor. Please refer to the respective plugin guide
2. 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

![](https://github-readme-stats.vercel.app/api/wakatime?username={yourusername}&api_domain=waka.hackclub.com&bg_color=2D3748&title_color=2F855A&icon_color=2F855A&text_color=ffffff&custom_title=Hackatime%20Week%20Stats&layout=compact)

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:

1. Install the browser extension from the official store (Firefox, Chrome)
2. Open the extension settings dialog
3. 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)
4. Save
5. 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