WakaTime GitHub Profile README Tutorial: Displaying Real Coding Hours & Tech Usage

1. GitHub Stats vs. WakaTime: The Fundamental Difference

Many developers wonder why their GitHub profile displays a massive slice of HTML or CSS in their language card when they spent 90% of their work week writing Go or Rust.

The reason lies in how GitHub analyzes code: GitHub calculates language percentages by total file byte volume across all your repositories. If you fork a repository containing a massive bundled JavaScript file or a minified SVG asset, that language artificially skews your statistics.

WakaTime solves this problem: By running as a lightweight plugin inside your IDE (VS Code, Cursor, IntelliJ IDEA, Neovim), WakaTime monitors active keystrokes and file focus. It measures actual time spent programming:

• Captures time spent across private enterprise repos, freelance client work, and local scripts.
• Eliminates distortions caused by vendor directories, node_modules, and large data blobs.
• Displays your genuine weekly, monthly, or all-time programming cadence.

2. Method A: The Instant SVG Card

The easiest method to display WakaTime data requires zero GitHub Actions configuration. It utilizes the WakaTime endpoint provided by GitHub Readme Stats:

<!-- Dynamic WakaTime SVG Card -->
<p align="center">
  <img src="https://github-readme-stats.vercel.app/api/wakatime?username=YOUR_WAKATIME_USERNAME&theme=tokyonight&layout=compact&cache_seconds=86400" alt="WakaTime Stats" />
</p>

WakaTime Endpoint Parameters:

• layout=compact: Formats stats into a clean two-column table.
• langs_count=6: Limits display to your top 6 languages to maintain a balanced card height.
• hide_progress=true: Hides percentage bars if you prefer a cleaner numerical readout.
• range=last_7_days (or all_time, last_30_days): Filters time horizons.

3. Method B: The ASCII Progress Bar GitHub Action

If you love pure terminal aesthetics and do not want to rely on external image servers, you can use Athul’s waka-readme GitHub Action. It automatically updates a text-based ASCII progress bar in your README every night:

# ⏱️ Weekly Coding Activity

```text
TypeScript   18 hrs 42 mins  ████████████████▒░░░░░░░  58.2 %
Go           7 hrs 15 mins   ███████▒░░░░░░░░░░░░░░░░  22.5 %
Python       3 hrs 50 mins   ███▒░░░░░░░░░░░░░░░░░░░░  11.9 %
SQL          1 hr 30 mins    █▒░░░░░░░░░░░░░░░░░░░░░░   4.6 %
```

Complete GitHub Action Workflow File:

Create .github/workflows/wakatime.yml in your profile repository:

name: Update WakaTime Readme

on:
  schedule:
    # Runs every night at midnight UTC
    - cron: '0 0 * * *'
  workflow_dispatch:

jobs:
  update-readme:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: athul/waka-readme@master
        with:
          WAKATIME_API_KEY: ${{ secrets.WAKATIME_API_KEY }}
          SHOW_TITLE: true
          BLOCKS: ->
          TIME_RANGE: last_7_days
          SHOW_TIME: true

4. Privacy & Client Data Protection