manualwakatime 0.2.0

Manual WakaTime tracker — send heartbeats with a live TUI

manualwakatime

Manual WakaTime tracker with a live terminal UI.
Sends heartbeats every 60 seconds while you work — no editor plugin required.

Works with the official WakaTime API and compatible backends like Hackatime.

┌──────────────────────────────────────────────┐
│                  Tracking                    │
│                                              │
│     Project:    my-awesome-project           │
│     Elapsed:    00:12:35                     │
│     Heartbeats: 12                           │
│     Last beat:  23s ago                      │
│     Status:     ● Running                    │
│                                              │
├──────────────────────────────────────────────┤
│     Press q or Ctrl+C to stop                │
└──────────────────────────────────────────────┘

Why?

Sometimes you aren't writing code in an editor. Maybe you're:

• Reviewing PRs in a browser
• Designing in Figma
• Writing docs in Notion
• Pair programming over a call

manualwakatime lets you track any activity as a WakaTime project with a single command. Fire and forget.

Install

pip install manualwakatime

Requires Python 3.8+.

Quick start

mwt start my-project

A fullscreen TUI opens. Heartbeats are sent every 60 seconds. Press q or Ctrl+C when you're done, and a summary prints:

  Stopped  Tracked 01:23:45  83 heartbeat(s) sent.

No project name? Run mwt start — it shows your recent projects and lets you pick one by number or type a new name.

Commands

mwt start <project>    Start tracking a project
mwt start              Pick from recent projects interactively
mwt projects           List all tracked projects
mwt config             Show API key / URL status
mwt --help             Show help

Configuration

API credentials are read from (highest priority first):

Source	Variable
Environment	WAKATIME_API_KEY
Environment	WAKATIME_API_URL
WakaTime config	~/.wakatime.cfg → api_key
WakaTime config	~/.wakatime.cfg → api_url

If no api_url is set, it defaults to https://api.wakatime.com/api/v1.

Example ~/.wakatime.cfg

[settings]
api_key = waka_your_api_key_here
api_url = https://api.wakatime.com/api/v1

Get your API key at wakatime.com/settings/api-key.

How it works

1. On startup, mwt reads your API key and URL from config or environment.
2. A background thread sends a heartbeat every 60 seconds.
3. The TUI refreshes 8 times per second, showing elapsed time, heartbeat count, and status.
4. Press q or Ctrl+C to stop cleanly — the alternate screen restores your terminal.

Project history is saved locally to %APPDATA%/mwt/projects.json (Windows) or ~/.config/mwt/projects.json (Linux/macOS).

License

MIT