Metadata-Version: 2.4
Name: manualwakatimetracker
Version: 0.2.0
Summary: Manual WakaTime tracker — send heartbeats with a live TUI
Author: benne
License-Expression: MIT
Project-URL: Homepage, https://github.com/anomalyco/mwt
Project-URL: Issues, https://github.com/anomalyco/mwt/issues
Keywords: wakatime,time-tracking,cli,tui
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0.0
Requires-Dist: requests>=2.28.0
Dynamic: license-file

<p align="center">
  <img src="https://img.shields.io/pypi/v/manualwakatime?color=blue" alt="PyPI">
  <img src="https://img.shields.io/pypi/pyversions/manualwakatime?color=blue" alt="Python">
  <img src="https://img.shields.io/pypi/l/manualwakatime?color=blue" alt="License">
</p>

# 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](https://wakatime.com) API and compatible backends like [Hackatime](https://hackatime.hackclub.com).

```
┌──────────────────────────────────────────────┐
│                  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

```bash
pip install manualwakatime
```

Requires Python 3.8+.

## Quick start

```bash
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`

```ini
[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](https://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
