System-End/hackatime
1
0
Fork 0
mirror of https://github.com/System-End/hackatime.git synced 2026-04-19 23:32:53 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Lots of docs improvements

Browse source
This commit is contained in:
Zach Latta 2025-05-28 17:49:39 -04:00
parent 257099e059
commit c3e62fb629
7 changed files with 188 additions and 246 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
app/views/docs/index.html.erb
View file

@ -2,9 +2,7 @@
<% content_for :meta_description, "Complete documentation for Hackatime - learn how to track your coding time and use our API." %>
<div class="container">
<p class="super">
Free & Open Source WakaTime Alternative
</p>
<h1 class="title">
Welcome to <span class="primary-color">Hackatime</span>
</h1>
@ -21,7 +19,7 @@
</p>
<p>
Hackatime is totally free. Anyone can see the code. It's like <a href="https://wakatime.com" target="_blank">WakaTime</a> but for Hack Club members.
Hackatime is totally free. Anyone can see the <a href="https://github.com/hackclub/hackatime" target="_blank">code</a>. It's like <a href="https://wakatime.com" target="_blank">WakaTime</a> but free and open source.
</p>
@ -85,8 +83,8 @@
<ul>
<li><strong>Open Source</strong>: You can see all the code on <a href="https://github.com/hackclub/hackatime" target="_blank">GitHub</a></li>
<li><strong>Private</strong>: We only see how long you code, not what you type</li>
<li><strong>Community Made</strong>: Built by Hack Club members</li>
<li><strong>Free</strong>: Free! You can donate to Hack Club at <a href="https://hackclub.com/donate" target="_blank">hackclub.com/donate</a></li>
<li><strong>Community Made</strong>: Built by Hack Club</li>
<li><strong>Free</strong>: You can donate to cover server costs at <a href="https://hackclub.com/donate" target="_blank">hackclub.com/donate</a></li>
</ul>
<h3>🆘 Need Help?</h3>
@ -96,7 +94,7 @@
</p>
<p>
<strong>Have questions?</strong> Ask in the <a href="https://hackclub.slack.com" target="_blank">Hack Club Slack</a>
(#hackatime channel) or <a href="https://github.com/hackclub/hackatime/issues" target="_blank">ask on GitHub</a>.
(#hackatime-dev channel) or <a href="https://github.com/hackclub/hackatime/issues" target="_blank">ask on GitHub</a>.
</p>
<hr style="margin: 2rem 0;">

85
docs/api/authentication.md
View file

@ -1,102 +1,93 @@
# Authentication
# How to Log In With Code
Learn how to authenticate with the Hackatime API.
Here's how to use your API key to access Hackatime data with code.
## API Key
## Get Your API Key
All API requests require authentication using your personal API key.
Every API request needs your personal API key.
### Getting Your API Key
### Finding Your API Key
1. Log in to [Hackatime](/)
2. Go to [Settings](/my/settings)
3. Copy your API key from the settings page
1. Log in to [Hackatime](https://hackatime.hackclub.com)
2. Go to [Settings](https://hackatime.hackclub.com/my/settings)
3. Copy your API key from the page
### Using Your API Key
Include your API key in the Authorization header:
Put your API key in the Authorization header:
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://hackatime.hackclub.com/api/v1/stats
```
## Alternative Authentication Methods
## Other Ways to Send Your Key
### Query Parameter
### In the URL
You can also pass your API key as a query parameter:
You can also put your API key in the URL:
```bash
curl "https://hackatime.hackclub.com/api/v1/stats?api_key=YOUR_API_KEY"
```
**Note**: Using the Authorization header is recommended for security.
**Note**: The Authorization header way is safer.
## Testing Authentication
## Test Your Key
Test your API key with a simple request:
Try your API key with this simple request:
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://hackatime.hackclub.com/api/v1/stats
```
A successful response will look like:
If it works, you'll get something like:
```json
{
"data": {
"total_seconds": 12345,
"languages": [...],
"editors": [...]
},
"success": true
"total_seconds": 12345,
"languages": [...],
"projects": [...]
}
```
## Error Responses
## What Happens When Something Goes Wrong
### Invalid API Key
### Wrong API Key
```json
{
"error": "Invalid API key",
"success": false
"error": "Invalid API key"
}
```
### Missing API Key
### No API Key
```json
{
"error": "API key required",
"success": false
"error": "API key required"
}
```
## Rate Limiting
## Rate Limits
* **Authenticated requests**: 100 per minute
* **Unauthenticated requests**: 10 per minute
We don't enforce hard limits right now, but be reasonable:
* Don't make thousands of requests per minute
* The WakaTime plugin automatically limits heartbeats to every 30 seconds
Rate limit headers are included in responses:
* `X-RateLimit-Limit`: Your rate limit
* `X-RateLimit-Remaining`: Requests remaining
* `X-RateLimit-Reset`: Unix timestamp when limit resets
## Keep Your Key Safe
## Security Best Practices
* **Never commit API keys** to version control
* **Use environment variables** to store API keys
* **Rotate keys regularly** if they may be compromised
* **Use HTTPS** for all API requests
* **Never put API keys in your code** that others can see
* **Use environment variables** to store your API key
* **Only use HTTPS** (never HTTP) for API requests
* **Get a new key** if you think yours was stolen
## Need Help?
If you're having authentication issues, check:
1. Your API key is correct
2. You're using the right API endpoint
3. Your request headers are properly formatted
Having trouble with your API key? Check:
1. You copied the whole key correctly
2. You're using the right website URL
3. Your request looks like the examples above
Still stuck? Reach out in [Hack Club Slack](https://hackclub.slack.com)!
Still stuck? Ask for help in [Hack Club Slack](https://hackclub.slack.com) (#hackatime-dev channel)!

136
docs/api/endpoints.md
View file

@ -1,45 +1,29 @@
# API Endpoints
# All the API Commands
Hackatime provides both WakaTime-compatible and native API endpoints for accessing your coding data.
Here are all the ways you can get data from Hackatime with code.
## Authentication
## How to Log In
All API requests require authentication via:
- **Header**: `Authorization: Bearer YOUR_API_KEY`
- **Query Parameter**: `?api_key=YOUR_API_KEY`
All requests need your API key:
- **Best way**: `Authorization: Bearer YOUR_API_KEY` in the header
- **Other way**: Add `?api_key=YOUR_API_KEY` to the URL
Get your API key from your [Hackatime dashboard settings](https://hackatime.hackclub.com/my/wakatime_setup).
Get your API key from [Hackatime settings](https://hackatime.hackclub.com/my/settings).
## WakaTime-Compatible Endpoints
## For WakaTime Tools
These endpoints are compatible with existing WakaTime tools and libraries.
These work with existing WakaTime apps and libraries.
### Push Heartbeats
```
POST /api/hackatime/v1/users/current/heartbeats
```
Send coding activity data (what editor plugins use automatically).
**Request Body** (JSON):
```json
[{
"type": "file",
"time": 1640995200,
"entity": "example.py",
"language": "Python",
"project": "my-project"
}]
```
### Status Bar Data
### Get Today's Time
```
GET /api/hackatime/v1/users/{user_id}/statusbar/today
```
Get today's coding time for status bar displays.
Shows how much you've coded today.
**Example Response**:
**What you get back**:
```json
{
"data": {
@ -51,25 +35,25 @@ Get today's coding time for status bar displays.
}
```
### Dashboard Redirect
## Hackatime-Only Commands
These are special to Hackatime.
### Your Coding Stats
```
GET /api/hackatime/v1/
GET /api/v1/stats
```
Redirects to the main dashboard.
Get how much you've coded overall.
## Native Hackatime API
Enhanced endpoints with additional features.
### User Statistics
### Someone Else's Stats
```
GET /api/v1/users/{username}/stats
```
Get comprehensive coding statistics for a user.
See someone else's public coding stats.
**Example Response**:
**What you get back**:
```json
{
"user": "username",
@ -84,93 +68,61 @@ Get comprehensive coding statistics for a user.
}
```
### Heartbeat Spans
```
GET /api/v1/users/{username}/heartbeats/spans
```
Get time spans of coding activity.
### My Heartbeats
### Your Raw Activity Data
```
GET /api/v1/my/heartbeats
GET /api/v1/my/heartbeats/most_recent
```
Access your own heartbeat data.
Get the raw data about when you coded.
**Query Parameters**:
- `start` - Start date (ISO 8601)
- `end` - End date (ISO 8601)
- `limit` - Number of results (default: 100)
**Options you can add**:
- `start` - Start date
- `end` - End date
- `limit` - How many results (max 100)
### Global Statistics
```
GET /api/v1/stats
```
Get platform-wide statistics (requires authentication).
### User Lookup
### Find Users
```
GET /api/v1/users/lookup_email/{email}
GET /api/v1/users/lookup_slack_uid/{slack_uid}
```
Look up users by email or Slack UID.
Find users by their email or Slack ID.
## Example Usage
## Try These Examples
### Get Your Recent Activity
### See Your Recent Activity
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://hackatime.hackclub.com/api/v1/my/heartbeats?limit=10"
```
### Send a Test Heartbeat
```bash
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '[{"type":"file","time":1640995200,"entity":"test.py","language":"Python"}]' \
"https://hackatime.hackclub.com/api/hackatime/v1/users/current/heartbeats"
```
### Get Today's Coding Time
### Get Today's Time
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://hackatime.hackclub.com/api/hackatime/v1/users/current/statusbar/today"
```
## Rate Limits
## Limits
- **Heartbeats**: 30-second rate limit between heartbeats (configurable in `~/.wakatime.cfg`)
- **API Requests**: Reasonable usage expected; no hard limits currently enforced
- **Heartbeats**: WakaTime plugins wait 30 seconds between sends
- **API Requests**: No hard limits, but don't go crazy
## Error Responses
## When Things Go Wrong
All errors return appropriate HTTP status codes with JSON error messages:
Errors look like this:
```json
{
"error": "Invalid API key",
"message": "The provided API key is invalid or expired"
"error": "Invalid API key"
}
```
Common status codes:
- `401` - Invalid or missing API key
- `404` - Resource not found
- `429` - Rate limit exceeded
- `500` - Server error
Common problems:
- `401` - Bad or missing API key
- `404` - That thing doesn't exist
- `500` - Something broke on our end
## Libraries & SDKs
Since Hackatime is WakaTime-compatible, you can use existing WakaTime libraries:
- **Python**: `wakatime-python`
- **JavaScript**: `wakatime-client`
- **Go**: `go-wakatime`
- **Ruby**: `wakatime-ruby`
Just configure them to use `https://hackatime.hackclub.com` as the base URL.

45
docs/api/overview.md
View file

@ -1,49 +1,48 @@
# API Overview
# How to Use Our Code API
The Hackatime API is compatible with WakaTime's API, allowing you to access your coding time data programmatically.
The Hackatime API lets you get your coding data with code. It works just like WakaTime's API.
## Quick Start
Get your API key from your Hackatime dashboard settings, then make requests to:
1. Get your API key from [Hackatime settings](https://hackatime.hackclub.com/my/settings)
2. Make requests to: `https://hackatime.hackclub.com/api/v1/`
```
https://hackatime.hackclub.com/api/v1/
```
## How to Log In With Code
## Authentication
Put your API key in your requests like this:
Include your API key in requests using either method:
**Authorization Header** (recommended):
**Best way (Authorization Header)**:
```
Authorization: Bearer YOUR_API_KEY
```
**Query Parameter**:
**Other way (in the URL)**:
```
?api_key=YOUR_API_KEY
```
## Basic Example
## Try It Out
Get your coding stats:
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://hackatime.hackclub.com/api/v1/users/current/stats
https://hackatime.hackclub.com/api/v1/stats
```
## WakaTime Compatibility
## Works With WakaTime Tools
Since Hackatime is compatible with WakaTime's API, you can:
- Use existing WakaTime libraries and SDKs
- Point WakaTime tools to `https://hackatime.hackclub.com`
- Import/export data between services
Since Hackatime works like WakaTime's API, you can:
- Use any WakaTime code libraries
- Point WakaTime tools to Hackatime
- Move data between WakaTime and Hackatime
## Common Endpoints
## Popular Endpoints
- **User Stats**: `/api/v1/users/current/stats` - Your coding statistics
- **Heartbeats**: `/api/v1/users/current/heartbeats` - Raw activity data
- **Leaderboard**: `/api/v1/leaders` - Community leaderboard data
- **Your Stats**: `/api/v1/stats` - How much you've coded
- **Your Heartbeats**: `/api/v1/my/heartbeats` - Raw coding activity
- **User Stats**: `/api/v1/users/{username}/stats` - Someone else's public stats
For detailed endpoint documentation, refer to the [WakaTime API docs](https://wakatime.com/developers) - most endpoints work identically with Hackatime.
## More Details
Want to see all the API commands? Check out our [complete API list](./endpoints). Most things work exactly like [WakaTime's API](https://wakatime.com/developers).

86
docs/getting-started/configuration.md
View file

@ -1,76 +1,74 @@
# Configuration
# Advanced Setup Stuff
Customize your Hackatime setup to get the most accurate time tracking.
Want to make Hackatime work better for you? Here are some extra things you can set up.
## Project Mapping
## Connect Your GitHub Projects
Map your local project folders to GitHub repositories for better insights:
Link your coding projects to GitHub so they show up better on leaderboards:
1. Go to [Projects](/my/projects)
2. Click on a project name
3. Enter the GitHub repository URL
4. Save your changes
1. First, authenticate with GitHub by going to [Projects](https://hackatime.hackclub.com/my/projects) and clicking "Sign in with GitHub"
2. This will automatically link your GitHub projects to your coding activity
3. If you need to override a project link, go to [Projects](https://hackatime.hackclub.com/my/projects) → click the pencil emoji (✏️) next to a project → set the GitHub URL
This helps link your coding time to specific repositories and enables features like:
* Repository links in leaderboards
* Better project organization
* Integration with GitHub stats
This helps because:
* Your projects show up with links on leaderboards
* Other people can see what you're building
* Your GitHub activity connects to your coding time
## Time Zone
## Set Your Time Zone
Set your correct time zone in [Settings](/my/settings) to ensure accurate daily/weekly statistics.
Make sure your daily stats are right by setting your time zone:
## Privacy Settings
1. Go to [Settings](https://hackatime.hackclub.com/my/settings)
2. Pick your time zone from the list
3. Save it
### What Gets Tracked
## What We Track (And What We Don't)
Hackatime tracks:
* **File names and paths** (for project detection)
* **Programming languages**
* **Editors used**
* **Time spent coding**
### What Hackatime Sees
### What Doesn't Get Tracked
Hackatime only tracks:
* **File names** (like `main.py` or `index.html`)
* **What language you're coding in** (like Python or JavaScript)
* **What editor you use** (like VS Code or Vim)
* **How long you code**
### What Hackatime Never Sees
Hackatime **never** tracks:
* File contents or code
* Keystrokes
* Screenshots
* Passwords or sensitive data
* What you type in your code
* Your passwords
* Screenshots of your screen
* Anything you type on your keyboard
## WakaTime Configuration
## Hide Files You Don't Want Tracked
You can also configure the WakaTime plugin directly:
### Exclude Files
Create a `.wakatime-project` file in your project root:
You can tell WakaTime to ignore certain files. Make a file called `.wakatime-project` in your project folder:
```
[settings]
debug = false
hidefilenames = false
exclude =
^/var/
\.log$
/node_modules/
/vendor/
*.log
/temp/
```
### Include Only Specific Files
This will ignore:
* `node_modules` and `vendor` folders
* Any `.log` files
* The `temp` folder
## Only Track Certain Projects
If you only want to track projects that have a `.wakatime-project` file:
```
[settings]
include_only_with_project_file = true
```
## API Configuration
For advanced users, you can configure the API endpoint in your WakaTime settings:
* **API URL**: `https://hackatime.hackclub.com/api/hackatime/v1`
* **Timeout**: 30 seconds (default)
## Need Help?
If you need assistance with configuration, reach out in [Hack Club Slack](https://hackclub.slack.com) or check our [troubleshooting guide](/docs/getting-started/troubleshooting).
Having trouble with setup? Ask for help in [Hack Club Slack](https://hackclub.slack.com) (#hackatime-dev channel)!

67
docs/getting-started/installation.md
View file

@ -1,34 +1,38 @@
# Installation
# Add Plugins to Your Editor
Follow these steps to set up time tracking with Hackatime.
Here's how to add WakaTime plugins to your code editor so Hackatime can track your coding time.
## Prerequisites
## What You Need
Before you begin, make sure you have:
* A code editor (VS Code, IntelliJ, Vim, etc.)
Before you start, make sure you have:
* A code editor (like VS Code, PyCharm, Vim, etc.)
* A [Hackatime account](/)
## Install the WakaTime Plugin
## Step 1: Do the Automated Setup
Hackatime uses the WakaTime ecosystem for time tracking. Install the appropriate plugin for your editor:
**First, use the [setup page](https://hackatime.hackclub.com/my/wakatime_setup)!** It automatically sets up your API key and endpoint so everything works perfectly.
### Visual Studio Code
## Step 2: Add WakaTime Plugin
After doing the automated setup, install the WakaTime plugin for your editor:
### VS Code
1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "WakaTime"
2. Click the Extensions button (or press Ctrl+Shift+X)
3. Type "WakaTime" in the search box
4. Click Install
### IntelliJ IDEA / PyCharm / WebStorm
### PyCharm / IntelliJ
1. Go to File → Settings (or IntelliJ IDEA → Preferences on macOS)
2. Select Plugins
3. Search for "WakaTime"
4. Install and restart your IDE
1. Go to File → Settings (on Mac: IntelliJ IDEA → Preferences)
2. Click Plugins
3. Type "WakaTime" in the search box
4. Install and restart your app
### Vim/Neovim
### Vim
For Vim users, install vim-wakatime:
Copy and paste this into your terminal:
```bash
git clone https://github.com/wakatime/vim-wakatime.git ~/.vim/bundle/vim-wakatime
@ -36,24 +40,25 @@ git clone https://github.com/wakatime/vim-wakatime.git ~/.vim/bundle/vim-wakatim
### Sublime Text
1. Open Package Control (Ctrl+Shift+P)
1. Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
2. Type "Install Package"
3. Search for "WakaTime"
4. Install the package
3. Type "WakaTime"
4. Install it
## Configure Your API Key
### Other Editors
1. Get your API key from your [Hackatime settings](/my/settings)
2. When prompted by the plugin, enter:
* **API Key**: Your Hackatime API key
* **API URL**: `https://hackatime.hackclub.com/api/hackatime/v1`
Visit [wakatime.com/plugins](https://wakatime.com/plugins) to find plugins for 40+ other editors.
## Verify Installation
## Already Have the Plugin Installed?
After setup, your coding time should automatically start being tracked. Check your [dashboard](/) to see your stats!
If you already have a WakaTime plugin, just run the [setup page](https://hackatime.hackclub.com/my/wakatime_setup) to switch it to Hackatime. It will automatically update your settings.
## Troubleshooting
## Check If It's Working
* **Not seeing data?** Make sure your API URL is correctly set
* **Plugin not working?** Try restarting your editor
* **Need help?** Reach out in the [Hack Club Slack](https://hackclub.slack.com)
After setup, start coding! Your time will show up on your [Hackatime dashboard](https://hackatime.hackclub.com) in a few minutes.
## Need Help?
* **Not seeing your time?** Make sure the API URL is set correctly
* **Plugin not working?** Try closing and opening your editor again
* **Still stuck?** Ask for help in [Hack Club Slack](https://hackclub.slack.com) (#hackatime-dev channel)

3
docs/getting-started/quick-start.md
View file

@ -10,7 +10,6 @@ Hackatime is a **free and open source** alternative to WakaTime that automatical
Visit [hackatime.hackclub.com](https://hackatime.hackclub.com) and sign up using:
- Your Hack Club Slack account (recommended)
- GitHub account
- Email address
## Step 2: Run Automated Setup
@ -79,7 +78,7 @@ Check that it's working:
**Need help?**
- Visit the [Hackatime Setup Page](https://hackatime.hackclub.com/my/wakatime_setup) for guided troubleshooting
- Join [Hack Club Slack](https://hackclub.slack.com) (#hackatime channel)
- Join [Hack Club Slack](https://hackclub.slack.com) (#hackatime-dev channel)
- [Create an issue](https://github.com/hackclub/hackatime/issues) on GitHub
**Migrating from WakaTime?**