worktick 0.2.2

Local CLI for tracking tasks, git commits, and generating summaries

worktick

A local CLI tool for tracking tasks, capturing git commits, and generating copy-paste-ready summaries for Trello/Slack/standup.

No cloud. No accounts. Just Python + optional local AI tools.

Why

Manual time tracking (browser extensions, web apps) is tedious. Your org just wants quantified task output — they don't care about the tool. This CLI tracks time locally, auto-captures git commits, and generates markdown summaries you can paste anywhere.

Install

From PyPI (recommended):

uv tool install worktick
# or: pip install worktick

This installs both worktick and wt (short alias) commands globally.

From source:

uv tool install .

After code changes, reinstall with:

uv tool install . --force --reinstall

Dev install:

uv sync
uv run wt --help

Setup (Optional)

The core commands (start, stop, note, list, summary, cancel, edit, repo) need nothing extra. The tools below unlock AI-powered features.

Ollama

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

brew install ollama
ollama serve &                 # keep running in background
ollama pull gemma3             # ~5GB, fits Apple Silicon 16GB well

whisper.cpp

Local speech-to-text. Required for audio transcription — both wt mom listen/stop (live recording) and wt mom file <audio-file> (pre-recorded). Not needed for text input (wt mom file notes.txt or pbpaste | wt mom file -).

brew install whisper-cpp

This installs the whisper-cli binary. You also need a GGML model file:

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

For faster transcription with slightly lower accuracy, use the base model (~150MB):

curl -L -o ~/.cache/whisper/ggml-base.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin

All available models: https://huggingface.co/ggerganov/whisper.cpp/tree/main

sox (preferred) or ffmpeg

Required only for live mic recording (wt mom listen). Sox is preferred — it's purpose-built for audio and produces cleaner recordings for transcription. ffmpeg works as a fallback if you already have it.

brew install sox              # recommended (~5 MB)
# OR skip if you already have ffmpeg installed

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

For a detailed breakdown of each tool and why it was chosen, see docs/tools.md.

Commands

Both worktick and wt work as the CLI command. Examples use wt for brevity.

Core

wt start "title" [--card URL]                              # start timer
wt stop [--at HH:MM]                                       # stop timer, capture commits
wt status                                                   # current task + elapsed time
wt pause                                                    # pause task timer
wt resume                                                   # resume paused task timer
wt note "text"                                              # add note to current task
wt list [--days N]                                          # recent tasks
wt summary [today|yesterday|week]                           # markdown summary → clipboard
wt repo [path]                                              # register git repo(s)
wt cancel                                                   # discard current task
wt edit ID [--title T] [--card U]                           # edit a past task

AI-Powered

wt daily [today|yesterday|week] [--model M] [--no-copy]    # compact hours summary
wt mom listen                                               # start recording from mic
wt mom pause                                                # pause recording
wt mom resume                                               # resume recording
wt mom stop [--model M] [--no-copy]                         # stop → transcribe → minutes
wt mom file <path> [--model M] [--no-copy]                  # minutes from file or '-' for stdin
wt mom list                                                 # list all saved meetings
wt mom show <id>                                            # view meeting minutes
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/retry	—	—	—

Three Types of Work

Work type	How it's captured
Coding (git repos)	Auto — git commits captured on wt stop
Tool work (n8n, Claude, etc.)	Manual — wt note "what I did"
Meetings	wt mom listen/stop or wt note "discussed X"

Multi-Repo Git Integration

Git repos are automatically detected from your working directory when you run start, stop, note, or status. You can also register repos explicitly:

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.

Multi-account Git setups

If you use includeIf in your ~/.gitconfig to set different user.email per workspace (e.g., personal vs work), commit filtering works automatically — git config user.email is resolved per-repo directory, so the correct author email is used.

Note: Currently the author email is resolved once from your cwd at wt stop time, not per-repo. If a single task spans repos across different workspaces (e.g., personal + work), run wt stop from the workspace whose commits you want captured — or register repos from only one workspace per task.

Example Workflow

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

Example Output

wt summary

## 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

Compact format with hours, ideal for quick standups. Titles are cleaned up by Ollama if available, otherwise raw titles are used.

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

Record live or process a file:

wt mom listen              # start recording from mic
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 (ollama only)
pbpaste | wt mom file -    # from clipboard (ollama only)
wt mom file meeting.wav    # from audio file (whisper + ollama)

Browse and retry past meetings:

wt mom list
# Meetings:
#   [+] abc123  09 Mar 10:00  recording  completed
#   [x] def456  09 Mar 14:30  recording  failed [audio: exists]
#   [+] ghi789  08 Mar 16:00  file       completed

wt mom show abc123         # view minutes
wt mom retry def456        # retry failed (skips transcription if transcript is saved)

Recording details:

• Records mono 16kHz WAV (~1.9 MB/min, ~115 MB/hr, ~345 MB for 3hr)
• Runs in background — works even if you switch away from the terminal
• Auto-stops after 4 hours to prevent runaway recordings
• Pause/resume creates segments that are merged on stop
• Audio auto-deleted on success, preserved on failure for retry
• All meetings (success + failed) are saved persistently — safe to clear the screen

Data Storage

Everything lives in ~/.task-tracker/:

File	Purpose
tasks.json	Task entries with timestamps, commits, notes
meetings.json	Meeting minutes with transcript, status, audio path
recording.json	Active recording state (PID, segments) — auto-cleaned on stop

All writes are atomic (temp file + os.replace()). Timestamps are ISO 8601 with timezone. Duration is calculated from start/stop, so sleep mode doesn't affect anything.

Design Decisions

• Minimal dependencies — typer, rich, pydantic, httpx (no heavy frameworks)
• No background process — timestamps only, duration calculated on the fly
• Atomic writes — temp file + os.replace() to prevent data corruption
• Graceful degradation — AI features fail with clear setup instructions; core commands always work
• Meeting persistence — every meeting saved (success + failure) so nothing is lost
• Safe recording — 4hr max, auto-cleanup on success, retry on failure
• Prefix matching — short IDs work everywhere (wt edit abc, wt mom show abc)

Roadmap

• Ollama integration for meeting minutes (wt mom)
• Compact daily summary with LLM-cleaned titles (wt daily)
• Live meeting recording with pause/resume (wt mom listen/stop)
• Persistent meeting storage with list/show/retry (wt mom list)
• n8n webhook to auto-push summaries to Trello/Slack
• Trello API integration (move cards, add comments)