Metadata-Version: 2.4
Name: worktick
Version: 1.1.1
Summary: Local CLI for tracking tasks, git commits, and generating summaries
Project-URL: Homepage, https://github.com/karprabha/worktick
Project-URL: Repository, https://github.com/karprabha/worktick
Project-URL: Issues, https://github.com/karprabha/worktick/issues
Author-email: Prabhakar Yadav <dev@karprabha.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,git,productivity,task,time-tracking
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Office/Business
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.15
Description-Content-Type: text/markdown

# worktick

**Track your work, capture git commits, generate summaries.** All local. No cloud. No accounts.

[![PyPI](https://img.shields.io/pypi/v/worktick)](https://pypi.org/project/worktick/)
[![Python](https://img.shields.io/pypi/pyversions/worktick)](https://pypi.org/project/worktick/)
[![License](https://img.shields.io/pypi/l/worktick)](https://github.com/karprabha/worktick/blob/main/LICENSE)

## Why

Time tracking shouldn't require browser extensions, web apps, or yet another account. Your org wants quantified task output — they don't care how you track it. But manually logging hours, copy-pasting commit messages, and formatting standup notes is tedious busywork.

**worktick** runs entirely on your machine. Start a timer, code as usual, and it auto-captures your git commits across repos. When you stop, it generates markdown summaries you can paste directly into Trello, Slack, or standup notes. Optional local AI tools add meeting minutes from mic recordings — no audio leaves your machine.

## Quick Start

```bash
pip install worktick

wt start "Fix auth bug"
# ... code, commit as usual ...
wt note "Tested in Postman"
wt stop
wt summary today
```

Output:

```markdown
## 2026-03-08 (Saturday)

**Fix auth bug** (2h 15m)
- Fix token refresh logic (abc123d)
- Add retry on 401 responses (def456a)
- Tested in Postman

**Total: 2h 15m**
```

Ready to paste into Trello, Slack, or your standup notes.

## Install

```bash
pip install worktick
```

Or with [uv](https://docs.astral.sh/uv/) (recommended for CLI tools):

```bash
uv tool install worktick
```

This installs two commands: `worktick` (full name) and `wt` (short alias). All examples below use `wt`.

## Help

```bash
wt --help                # list all commands
wt summary --help        # help for a specific command
wt mom --help            # list subcommands under mom
wt mom stop --help       # help for a nested subcommand
wt config --help         # list subcommands under config
```

Every command and subcommand supports `--help`.

## Commands

### Core

These work out of the box — no extra setup needed.

| Command | Description |
|---------|-------------|
| `wt start "title" [--card URL]` | Start a new task timer |
| `wt stop [--at HH:MM]` | Stop timer, capture git commits |
| `wt status` | Show current task and elapsed time |
| `wt pause` / `wt resume` | Pause and resume the timer |
| `wt note "text"` | Add a note to the current task |
| `wt list [--days N]` | List recent tasks |
| `wt summary [today\|yesterday\|week] [--edit] [--push]` | Generate markdown summary (+ webhook) |
| `wt daily [today\|yesterday\|week] [--edit] [--push]` | Compact hours summary (Ollama optional, + webhook) |
| `wt repo [path]` | Register git repo(s) |
| `wt cancel` | Discard the current task |
| `wt edit ID [--title T] [--card U]` | Edit a past task |
| `wt config set <key> <value>` | Set config (e.g. webhook_url) |
| `wt config show` | Show current config |
| `wt config unset <key>` | Clear a config value |

### Meeting Minutes

These require optional AI tools (see [Setup](#setup-for-ai-features) below).

| Command | Description |
|---------|-------------|
| `wt mom listen` | Start recording from mic |
| `wt mom pause` / `wt mom resume` | Pause and resume recording |
| `wt mom stop [--model M]` | Stop, transcribe, generate minutes |
| `wt mom file <path> [--model M]` | Generate minutes from a file or stdin |
| `wt mom list` | List all saved meetings |
| `wt mom show <id> [--transcript]` | View minutes (or raw transcript with `-t`) |
| `wt mom edit <id>` | Edit minutes in $EDITOR |
| `wt mom push <id> [--edit]` | Push meeting minutes to webhook |
| `wt mom retry <id> [--model M]` | Retry a failed meeting |

**What needs what:**

| Command | Ollama | whisper.cpp | sox/ffmpeg |
|---------|--------|-------------|------------|
| `wt daily` | optional | — | — |
| `wt mom file <text-file>` | required | — | — |
| `wt mom file <audio-file>` | required | required | — |
| `wt mom listen/stop` | required | required | required |
| `wt mom list/show/edit/push/retry` | — | — | — |

## Example Workflow

```bash
wt start "Fix auth bug" --card https://trello.com/c/xxx
wt repo /path/to/workspace/myorg

# code, commit as usual...
git commit -m "Fix token refresh logic"
wt note "Tested flow in Postman"

wt stop
wt summary today
```

### `wt summary` output

```markdown
## 2026-03-08 (Saturday)

**Fix auth bug** (2h 15m) [Trello](https://trello.com/c/xxx)
- Fix token refresh logic (abc123d)
- Add retry on 401 responses (def456a)
- Tested flow in Postman

**Build email automation** (1h 30m) [Trello](https://trello.com/c/yyy)
- Created webhook trigger for new signups
- Connected to SendGrid email node

**Daily standup** (15m)
- Sprint planning for next week

**Total: 4h 00m**
```

### `wt daily` output

Compact format for quick standups. Titles cleaned up by Ollama if available.

```
Sat, 08 Mar 2026 - 4.00H

- 2.25H - Fixed auth token refresh and added retry on 401
- 1.50H - Built email automation with SendGrid webhooks
- 0.25H - Daily standup
```

### `wt mom` — meeting minutes

```bash
wt mom listen              # start recording
wt mom pause               # pause during break
wt mom resume              # resume
wt mom stop                # stop → transcribe → generate minutes

wt mom file transcript.txt  # from text file
wt mom file meeting.wav    # from audio file
pbpaste | wt mom file -    # from clipboard (macOS)
```

## Webhook Push

Push summaries to an n8n webhook (or any URL that accepts JSON POST) for forwarding to Trello, Slack, etc.

```bash
wt config set webhook_url https://n8n.example.com/webhook/abc123
wt summary today --push     # prints summary + POSTs to webhook
wt daily --push              # prints daily + POSTs to webhook
wt mom push <id>             # push meeting minutes to webhook
```

Summaries and daily reports always print and copy to clipboard first. `--push` then sends the markdown to your webhook. For meeting minutes, use `wt mom push <id>` after reviewing with `wt mom show <id>`. Webhook failures are warnings — they never block output.

## Multi-Repo Git Tracking

Git repos are auto-detected from your working directory. You can also register repos explicitly:

```bash
wt repo /path/to/repo              # single repo
wt repo /path/to/workspace/org     # scan children for git repos
```

On `wt stop`, commits are scanned from **all** registered repos.

## Setup for AI Features

The core commands work with zero setup. The tools below are only needed for AI-powered features (`wt daily` title cleanup, `wt mom` meeting minutes).

### 1. Ollama — Local LLM

Required for `wt mom` (meeting minutes). Optional for `wt daily` (cleans up task titles — falls back to raw titles without it).

**macOS:**

```bash
brew install ollama
```

**Linux:**

```bash
curl -fsSL https://ollama.com/install.sh | sh
```

**Windows:**

Download from [ollama.com/download](https://ollama.com/download/windows).

**Then pull a model and start the server:**

```bash
ollama pull gemma3             # ~5GB, works well on 16GB RAM
ollama serve                   # keep running in background
```

### 2. whisper.cpp — Local Speech-to-Text

Required for audio transcription (`wt mom listen/stop` and `wt mom file <audio-file>`). Not needed for text input (`wt mom file notes.txt`).

**macOS:**

```bash
brew install whisper-cpp
```

**Linux / Build from source:**

```bash
git clone https://github.com/ggerganov/whisper.cpp.git
cd whisper.cpp && cmake -B build && cmake --build build --config Release
sudo cp build/bin/whisper-cli /usr/local/bin/
```

**Windows:**

Download pre-built binaries from [whisper.cpp releases](https://github.com/ggerganov/whisper.cpp/releases) and add `whisper-cli` to your PATH.

**Then download a model:**

```bash
mkdir -p ~/.cache/whisper

# Medium model (~1.5GB) — best accuracy
curl -L -o ~/.cache/whisper/ggml-medium.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium.bin

# Or base model (~150MB) — faster, slightly lower accuracy
curl -L -o ~/.cache/whisper/ggml-base.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin
```

All models: [huggingface.co/ggerganov/whisper.cpp](https://huggingface.co/ggerganov/whisper.cpp/tree/main)

### 3. sox or ffmpeg — Audio Recording

Required only for live mic recording (`wt mom listen`). sox is preferred for cleaner audio. ffmpeg works as a fallback.

**macOS:**

```bash
brew install sox              # recommended
```

**Linux (Debian/Ubuntu):**

```bash
sudo apt install sox          # recommended
# or: sudo apt install ffmpeg
```

**Linux (Fedora/RHEL):**

```bash
sudo dnf install sox
# or: sudo dnf install ffmpeg
```

**Windows:**

```bash
# With Chocolatey
choco install sox
# or: choco install ffmpeg

# With Scoop
scoop install sox
# or: scoop install ffmpeg
```

The code tries sox first, falls back to ffmpeg automatically.

## Data Storage

All data is stored locally in `~/.worktick/` as JSON files:

| File | Purpose |
|------|---------|
| `tasks.json` | Task entries with timestamps, commits, notes |
| `meetings.json` | Meeting minutes with transcript, status, audio path |
| `recording.json` | Active recording state — auto-cleaned on stop |
| `config.json` | Configuration (webhook URL, audio device) |

All writes are atomic (temp file + rename) to prevent corruption. No data leaves your machine.

## System Audio Recording

Capture Google Meet, Zoom, or Teams audio with [BlackHole](https://github.com/ExistentialAudio/BlackHole):

```bash
brew install blackhole-2ch
wt config set audio_device "BlackHole 2ch"
```

Set up a Multi-Output Device in Audio MIDI Setup so you hear audio AND it routes to BlackHole. See the [full README](https://github.com/karprabha/worktick#system-audio-recording-google-meet-etc) for details.

## License

[MIT](https://github.com/karprabha/worktick/blob/main/LICENSE)
