worktick 0.2.0

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

task-tracker

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

Global install (recommended):

uv tool install .

This makes task available everywhere — no uv run prefix needed. After code changes, reinstall with:

uv tool install . --force --reinstall

Dev install:

uv sync
uv run task --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 task mom (meeting minutes). Optional for task 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 task mom listen/stop (live recording) and task mom file <audio-file> (pre-recorded). Not needed for text input (task mom file notes.txt or pbpaste | task 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 (task 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

Core

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

AI-Powered

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

What needs what:

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

Three Types of Work

Work type	How it's captured
Coding (git repos)	Auto — git commits captured on task stop
Tool work (n8n, Claude, etc.)	Manual — task note "what I did"
Meetings	task mom listen/stop or task 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:

task repo /path/to/repo                    # single repo
task repo /path/to/workspace/org           # scan children for git repos

On task 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 task stop time, not per-repo. If a single task spans repos across different workspaces (e.g., personal + work), run task stop from the workspace whose commits you want captured — or register repos from only one workspace per task.

Example Workflow

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

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

task stop
task summary today

Example Output

task 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**

task 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

task mom

Record live or process a file:

task mom listen              # start recording from mic
task mom pause               # pause during break
task mom resume              # resume
task mom stop                # stop → transcribe → generate minutes

task mom file transcript.txt  # from text file (ollama only)
pbpaste | task mom file -    # from clipboard (ollama only)
task mom file meeting.wav    # from audio file (whisper + ollama)

Browse and retry past meetings:

task 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

task mom show abc123         # view minutes
task 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 (task edit abc, task mom show abc)

Roadmap

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