Quick Start

git clone https://github.com/peab-dev/WorkTracker.git
cd WorkTracker

./install.sh

source ~/.zshrc   # or: wtrl
wt status

Requirements

Python Dependencies

Installation

./install.sh

The installer:

1. Checks prerequisites (macOS, Xcode CLI Tools, Python 3).
2. Offers to install Homebrew and Python if missing.
3. Copies the project to ~/WorkTracker.
4. Creates data/, logs/, summaries/.
5. Builds a Python venv and installs dependencies.
6. Generates 4 launchd plists and loads them.
7. Adds shell aliases (wts, wtd, wtx, …) to your shell config.

macOS Permissions

Grant access to your Terminal app (Terminal.app, iTerm2, Warp, …).

Uninstall

./uninstall.sh

• Stops and removes all launchd services.
• Removes shell aliases.
• Optionally deletes collected data.

CLI Commands

All commands run via the wt CLI:

wt <command>

Overview

Collector

Aggregator

Dashboards

Maintenance

Shell Aliases

Installed into your shell config by install.sh:

Dashboards

Terminal Dashboard

wt dash — curses UI with a 2 s refresh:

• Service status (running / ready / not loaded)
• Current app, window title, live input rates
• Today: active time, sessions, focus count, app switches
• Project breakdown with intensity bars
• Recent session timeline and latest report files

Web Dashboard

wt web starts Flask on http://127.0.0.1:7880. Same data, richer charts: hourly activity, project distribution, top apps, session timeline, service and log monitoring. Override the port via the PORT env var:

PORT=8000 wt web

Menubar Widget

wt menubar attaches a live stats icon to the macOS menu bar. It polls /api/live every 30 s and — if the web dashboard is not already running — spawns it in the background on port 7880. Click the icon to open the full web view.

Rhythm Heatmap

wt rhythm [weeks] renders a weekly activity heatmap from summaries/daily/*.md. Each cell is one hour; the “healthy” window is 09:00–22:00. Pass a number to look further back:

wt rhythm      # last 1 week
wt rhythm 4    # last 4 weeks
wtrh 8         # last 8 weeks

Statistics & Screenshots Explorer

The web dashboard ships three extra pages on top of the main view:

All three pages are reachable once wt web is running.

HTTP API

Everything the dashboard renders is backed by JSON endpoints you can script against:

Reports

Reports are Markdown files generated by the aggregator. They are the structured input Claude Cowork (or any other summarizer) consumes.

Daily

Generated at 22:00 → summaries/daily/YYYY-MM-DD.md

• Overview: active time, focus sessions, app switches, idle ratio.
• Project distribution: time, share, sessions, avg session, intensity.
• App usage: top apps by time.
• Timeline: full session-by-session table with topic and (optional) motivation message.
• Parallel media: music and video playing alongside work.
• Input analysis: keystroke peak hours, hourly intensity bars.
• Git activity: commits per repo (if enabled).
• Calendar & time classification: meetings vs. deep work.
• Previous day comparison: delta metrics.

Weekly

Generated Sunday 23:00 → summaries/weekly/YYYY-Wnn.md: aggregated week (Mon–Sun), daily comparison, project distribution, most/least productive day, previous-week delta.

Monthly

Generated 1st of month 00:30 → summaries/monthly/YYYY-MM.md: full month aggregation, weekly comparison, long-term trend (1st vs. 2nd half), previous-month delta.

Topic & Motivation Enrichment

If you enable the local LLM blocks (see Topic LLM, Motivation LLM), every eligible session in a report carries:

• Topic — a short German phrase (2–20 words) describing what the session was about, produced by topic_extractor.py.
• Topic long — 1–2 sentences, ≤280 chars, same pipeline.
• Motivation message — a one-line German motivational note, produced by motivation_extractor.py from up to N session screenshots via a local vision LLM.

Maintenance

Backfill Missing Reports

wt past (alias wt p) scans data/snapshots/ for days that have no daily report and for ISO weeks with no weekly report, then runs the aggregator for each. The current (incomplete) week is skipped.

Reprocess

wt reprocess (alias wt rp) re-runs every day in your snapshot history through the aggregator with the current project_patterns.yaml and LLM config. Use this after tweaking patterns, raising LLM quality, or changing session thresholds.

Compress Screenshots

Screenshots pile up fast. wt compress walks data/screenshots/, converts every PNG to JPEG via native sips, and leaves only images younger than 10 s alone so it never races the running collector.

wt compress                           # everything (incl. today, >10 s old)
wt compress --dry-run                 # preview savings only
wt compress --date 2026-04-10         # one specific day
wt compress --quality 60 --skip-today # tighter quality, spare today’s folder

Override the source directory with the SCREENSHOTS_DIR env var.

Configuration

Everything lives in one file:

~/WorkTracker/daemon/config.yaml

Collector Settings

Screenshots

Distraction Notifications

Aggregator Settings

Topic LLM

Sends session briefs (app, window title, URL host, filename, project, duration, activity counts) to a local OpenAI-compatible chat endpoint and writes a short German topic back into every session. Clipboard samples are never sent.

Motivation LLM (Vision)

Sends up to N session screenshots to a local vision-capable chat endpoint and writes a one-line German motivation message to session["motivation_message"]. Needs a vision model (e.g. qwen3-vl-8b, llava).

Project Patterns

Projects are matched by window title and URL patterns in:

~/WorkTracker/daemon/project_patterns.yaml

Example

projects:
  MyProject:
    patterns: ["*myproject*", "*MyProject*"]
    category: "Development"
  AI Research:
    patterns: ["*claude*", "*openai*", "*chatgpt*"]
    category: "AI/Research"
  Crypto:
    patterns: ["*binance*", "*bitcoin*"]
    url_patterns: ["*binance.com*", "*coingecko.com*"]
    category: "Crypto"

default_project: "Other"

Glob syntax (* = wildcard), case-insensitive match against window titles. URL patterns apply when track_browser_urls is on.

Web Categories

daemon/web_categories.py is a stdlib-only knowledge base mapping domains to a two-level hierarchy (main_category, subcategory) — Development / Code Hosting, Development / Q&A, Social Media / …, Media/Entertainment / …. The aggregator uses it to build the “Browsing Analysis” section of each report and to evaluate distraction thresholds against notifications.distraction_categories.

Add new domains by editing the DOMAIN_CATEGORIES dict at the top of the file — no config, no restart.

How It Works

WorkTracker follows a 4-layer architecture: collect → aggregate → enrich → summarize.

Directory Structure

Launchd Services

All services run with Nice: 10 (low priority) and log to ~/WorkTracker/logs/.

Collector Deep Dive

Long-running Python daemon. Every few seconds it writes one JSON snapshot.

What It Captures

Input Monitoring

Uses CGEventTap in listen-only mode on a dedicated CFRunLoop thread — it can observe events but cannot inject them.

Focus Detection

Uses AXUIElementCopyAttributeValue instead of NSWorkspace.frontmostApplication so floating overlays (e.g. the Claude Cowork widget) don’t steal the “frontmost” label.

Aggregator Deep Dive

Execution Modes & Flags

python aggregator.py --mode daily                    # today
python aggregator.py --mode daily --date 2026-04-01  # specific date
python aggregator.py --mode weekly
python aggregator.py --mode monthly

Pipeline

1. Load JSONL snapshots into a Pandas DataFrame.
2. Flatten nested fields (active_app, input, clipboard, system, media, git).
3. Build sessions via two-tier merging (see below).
4. Match each session to a project via pattern rules.
5. Classify URLs through web_categories.py.
6. Compute stats (time distribution, intensity, focus sessions).
7. Enrich via topic LLM and motivation vision LLM (if enabled).
8. Render Markdown report with tables.
9. Run pattern learning on “Other” sessions.

Session Detection

Sessions group consecutive snapshots that represent one work context.

Tier 1 — same app, small gap

Same app within same_app_grace_period_seconds → always merge. Handles rapid tab switching.

Tier 2 — same app, larger gap

Larger gap but same app → merge only if window titles hit the fuzzy threshold (Levenshtein ratio ≥ fuzzy_match_threshold).

Split triggers

• Different app.
• Idle gap exceeds idle_threshold_seconds.
• Sleep/wake event.
• Title similarity drops below the fuzzy threshold.

Micro-session absorption

Sessions with fewer than min_session_snapshots are absorbed into the preceding session to cut noise.

Pattern Learning

Unclassified (“Other”) sessions are used to suggest new project patterns automatically.

1. After daily aggregation, “Other” sessions are analyzed.
2. Window titles and URL hosts are grouped by keyword/domain.
3. Groups with ≥ 5 min total become pattern suggestions.
4. Suggestions are written to learned_patterns.yaml.

Priority

Static patterns in project_patterns.yaml always win. Hand-curated rules are never overridden.

Learned Pattern Format

projects:
  github.com:
    patterns: ["*github.com*"]
    url_patterns: ["*github.com*"]
    category: "auto-learned"
    _auto_generated: true
    _total_time_seconds: 3240
    _first_seen: "2026-04-01"
    _sample_titles: ["Issues - anthropics/claude-code"]

Interactive Review

daemon/review_patterns.py is a small TTY tool that walks through every learned_patterns.yaml suggestion and lets you keep, rename, or discard it interactively. Accepted entries are promoted into project_patterns.yaml.

python3 ~/WorkTracker/daemon/review_patterns.py

Run it after a week of data has accumulated — it’s the fastest way to turn noisy auto-learned patterns into clean, curated project rules.

Special Features

Sleep/Wake Detection

• Explicit: NSWorkspace sleep/wake notifications.
• Heuristic: loop iteration > 3× expected interval → gap record inserted.

Midnight Continuity

The daily aggregator loads the previous day’s tail (≥ 23:55) so sessions spanning midnight merge cleanly.

Intensity Scoring

Normalized input activity (keystrokes + clicks + scrolls over session duration) rendered as 10-character bar charts in reports and dashboards.

Focus vs. Deep Work

Sessions longer than focus_session_min_seconds are “focus sessions”; sessions past deep_work_min_minutes are promoted to deep work.

Browser URL Tracking

Reads SQLite history databases directly for Safari, Chrome, Firefox, Brave, Arc and Edge. URLs are matched against url_patterns and fed through web_categories.py.

Media Detection

Native apps (Spotify, Apple Music, VLC, IINA, Podcasts) via their own APIs; browser tabs (YouTube, Netflix, Twitch, SoundCloud) via window-title pattern matching. Parallel media is tracked alongside work sessions and shown in the report.