Metadata-Version: 2.4
Name: worktick
Version: 0.2.2
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: karprabha <dev@karprabha.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,git,productivity,task,time-tracking
Classifier: Development Status :: 4 - Beta
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

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):**

```bash
uv tool install worktick
# or: pip install worktick
```

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

**From source:**

```bash
uv tool install .
```

After code changes, reinstall with:

```bash
uv tool install . --force --reinstall
```

**Dev install:**

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

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

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

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

```bash
# 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):

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

```bash
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](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:

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

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

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

## Example Output

### `wt summary`

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

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

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

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

- [x] Ollama integration for meeting minutes (`wt mom`)
- [x] Compact daily summary with LLM-cleaned titles (`wt daily`)
- [x] Live meeting recording with pause/resume (`wt mom listen/stop`)
- [x] 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)
