Wakapi: Self-Hosted Coding Time Tracking as a WakaTime Alternative

Knowing where your coding time actually goes is surprisingly useful. Not for micromanaging yourself, but for understanding patterns: which projects consume the most effort, which languages you spend time in, whether that refactoring sprint actually took three days or three weeks. WakaTime is the most popular tool for this, but it sends your coding activity to their cloud. Every file you open, every project you switch to, every language you type in -- all of it flows through a third-party server.

Photo by Vertex Designs on Unsplash

Wakapi is a self-hosted, open-source alternative that is fully compatible with WakaTime's editor plugins. You install the same extensions in your editor, point them at your own server instead of WakaTime's API, and get the same insights without sharing your activity data with anyone.

What Wakapi Tracks

Every time you type in a supported editor, the WakaTime plugin sends a "heartbeat" to the server containing:

• Project name (detected from the git repo or folder name)
• Language (detected from the file extension)
• Editor (VS Code, Neovim, JetBrains, etc.)
• Operating system
• Branch (current git branch)
• File path (optional, can be disabled for privacy)
• Machine name (hostname of the device)

Wakapi aggregates these heartbeats into time summaries. If heartbeats arrive within a configurable timeout (default: two minutes), the time between them counts as coding time. Gaps longer than the timeout start a new coding session.

Docker Compose Setup

Wakapi is a single Go binary with an embedded SQLite database by default. The Docker setup is minimal:

services:
  wakapi:
    image: ghcr.io/muety/wakapi:latest
    container_name: wakapi
    ports:
      - "3000:3000"
    environment:
      WAKAPI_DB_TYPE: sqlite3
      WAKAPI_PASSWORD_SALT: "your-random-salt-string"
      WAKAPI_TRUSTED_HEADER_AUTH: "false"
      WAKAPI_INSECURE_COOKIES: "false"
    volumes:
      - wakapi_data:/data
    restart: unless-stopped

volumes:
  wakapi_data:

For production use with PostgreSQL:

services:
  wakapi:
    image: ghcr.io/muety/wakapi:latest
    container_name: wakapi
    ports:
      - "3000:3000"
    environment:
      WAKAPI_DB_TYPE: postgres
      WAKAPI_DB_HOST: wakapi-db
      WAKAPI_DB_PORT: "5432"
      WAKAPI_DB_NAME: wakapi
      WAKAPI_DB_USER: wakapi
      WAKAPI_DB_PASSWORD: "${WAKAPI_DB_PASSWORD}"
      WAKAPI_PASSWORD_SALT: "${WAKAPI_SALT}"
      WAKAPI_INSECURE_COOKIES: "false"
      WAKAPI_LISTEN_IPV4: "0.0.0.0"
      WAKAPI_SERVER_BASE_URL: "https://wakapi.example.com"
    depends_on:
      - wakapi-db
    restart: unless-stopped

  wakapi-db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: wakapi
      POSTGRES_USER: wakapi
      POSTGRES_PASSWORD: "${WAKAPI_DB_PASSWORD}"
    volumes:
      - wakapi_db_data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  wakapi_db_data:

Start the stack and navigate to https://wakapi.example.com. Create an account, and you will get an API key on the settings page.

Editor Plugin Setup

The key insight: you do not install a separate Wakapi plugin. You install the standard WakaTime plugin for your editor and point it at your Wakapi server. Wakapi speaks the WakaTime API protocol.

VS Code

1. Install the WakaTime extension from the VS Code marketplace
2. When prompted for an API key, enter your Wakapi API key
3. Open VS Code settings (JSON) and add:

{
  "wakatime.apiUrl": "https://wakapi.example.com/api"
}

Alternatively, edit ~/.wakatime.cfg:

[settings]
api_url = https://wakapi.example.com/api
api_key = your-wakapi-api-key

Neovim

Using the wakatime/vim-wakatime plugin:

-- In your Neovim config (lazy.nvim example)
{
  "wakatime/vim-wakatime",
  lazy = false,
}

Then configure ~/.wakatime.cfg as shown above.

JetBrains IDEs (IntelliJ, PyCharm, WebStorm)

1. Install the WakaTime plugin from the JetBrains marketplace
2. Go to Settings > WakaTime > API Key and paste your Wakapi key
3. Set the API URL to https://wakapi.example.com/api

Terminal (Shell Integration)

For tracking time spent in terminal sessions:

# Install wakatime-cli
pip install wakatime

# Configure
cat > ~/.wakatime.cfg << 'EOF'
[settings]
api_url = https://wakapi.example.com/api
api_key = your-wakapi-api-key
EOF

# Add to .bashrc or .zshrc for terminal tracking
# This requires the bash-wakatime or zsh-wakatime plugin

The Wakapi Dashboard

Once heartbeats start flowing, the dashboard shows:

Summary View

• Total coding time for the selected period (today, this week, this month, custom range)
• Projects breakdown -- time per project, ranked
• Languages breakdown -- time per programming language
• Editors breakdown -- time per editor
• Operating systems -- time per OS
• Machines -- time per device

Insights

• Daily average coding time
• Streaks -- consecutive days with coding activity
• Peak hours -- when you code most during the day
• Language trends -- how your language usage changes over time

Leaderboards

If you run Wakapi for a team, the leaderboard shows coding time rankings. This is opt-in -- users can choose whether to appear on the leaderboard.

Goal Tracking

Wakapi supports coding goals -- set a target number of hours per day or week, and the dashboard tracks your progress. This is useful for:

• Maintaining consistent coding habits
• Ensuring side projects get regular attention
• Tracking time investment in learning new languages

Configure goals from the dashboard settings. You can set goals per project, per language, or for total coding time.

Wakapi vs WakaTime

Why Self-Host?

The main reasons to run Wakapi over WakaTime:

1. Privacy: Your coding activity stays on your server. WakaTime sees every project name, file path, and branch you touch.
2. Data retention: WakaTime's free tier only keeps two weeks of history. Wakapi keeps everything forever.
3. No vendor lock-in: Your data is in a database you control. Export or query it however you want.
4. Cost: WakaTime Premium is $9/month. Wakapi is free and runs on minimal resources.

What You Give Up

WakaTime Premium has deeper integrations (GitHub commit linking, Slack status updates, team management) and a more polished dashboard. If you need those integrations and do not mind the privacy trade-off, WakaTime is the more feature-complete product.

Embeddable Badges

Wakapi can generate badge images compatible with GitHub README files and websites:

![Wakapi Stats](https://wakapi.example.com/api/badge/your-username/interval:any/project:my-project)

Badge types include total time, time by project, time by language, and time by editor. Use them in your GitHub profile README to show your coding activity.

API Access

Wakapi exposes a WakaTime-compatible API at /api/v1/. This means tools built for WakaTime's API generally work with Wakapi too. Query your data programmatically:

# Get today's summary
curl -H "Authorization: Basic $(echo -n 'your-api-key' | base64)" \
  'https://wakapi.example.com/api/v1/users/current/summaries?range=today'

# Get all-time stats
curl -H "Authorization: Basic $(echo -n 'your-api-key' | base64)" \
  'https://wakapi.example.com/api/v1/users/current/all_time_since_today'

Resource Requirements

Wakapi is extremely lightweight:

• CPU: Negligible (Go binary, processes heartbeats asynchronously)
• RAM: 30-50 MB typical
• Storage: Grows slowly -- a year of solo coding generates roughly 50-100 MB in SQLite
• Network: Heartbeats are tiny JSON payloads, typically under 1 KB each

You can run Wakapi on the smallest VPS or container alongside other services without worry.

The Bottom Line

Wakapi does one thing well: it tracks your coding time privately. The WakaTime plugin compatibility means zero friction -- install the same editor plugins you would use anyway, change the API URL, and your coding activity stays on your server with unlimited retention. If you have ever wanted to know where your development hours actually go without handing that data to a third party, Wakapi is a ten-minute deploy that quietly runs in the background collecting insights you will eventually find invaluable.