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

The installer handles everything automatically:

./install.sh

What it does

1. Checks prerequisites (macOS, Xcode CLI Tools, Python 3)
2. Offers to install Homebrew and Python if missing
3. Copies project to ~/WorkTracker
4. Creates directory structure (data/, logs/, summaries/)
5. Sets up Python virtual environment + installs dependencies
6. Generates 4 launchd plist files
7. Installs and starts launchd services
8. Adds shell aliases (wts, wtl, wtr, etc.) to your shell config

macOS Permissions

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

Uninstall

./uninstall.sh

Prompts to confirm, then:

• Stops and removes all launchd services
• Removes shell aliases from your shell config
• Optionally deletes collected data (or keeps it)

CLI Commands

All commands are run via the wt CLI tool:

wt <command>

Overview

Collector

Aggregator

Dashboards

Shell Aliases

Installed automatically by install.sh into your shell config:

Dashboards

Terminal Dashboard

Run wt dash for a real-time curses-based UI showing:

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

Web Dashboard

Run wt web to start a Flask server on http://127.0.0.1:7880:

• Same data as terminal dashboard, rendered in a browser
• Hourly activity chart
• Project distribution
• Top apps by time
• Session timeline
• Service and log monitoring

Reports

Reports are Markdown files generated by the aggregator. They serve as input for AI-powered summaries (e.g. via Claude Cowork).

Daily Report

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

• Overview: Active time, time range, 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
• Parallel Activities: Media playing during work
• Input Analysis: Keystroke peak hours, hourly intensity bars
• Git Activity: Commits per repo (if enabled)
• Calendar & Time Classification: Meetings vs. deep work (if enabled)
• Previous Day Comparison: Delta metrics

Weekly Report

Generated Sunday 23:00 → summaries/weekly/YYYY-Wnn.md

• Aggregated stats for the full week (Mon–Sun)
• Daily comparison table
• Weekly project distribution
• Trends: most/least productive day
• Previous week comparison

Monthly Report

Generated 1st of month 00:30 → summaries/monthly/YYYY-MM.md

• Full month aggregation
• Weekly comparison table
• Monthly project distribution
• Long-term trend (1st half vs. 2nd half)
• Previous month comparison

Configuration

All configuration lives in a single file:

~/WorkTracker/daemon/config.yaml

Collector Settings

Distraction Notifications

Aggregator Settings

Project Patterns

Projects are matched by window title and URL patterns in:

~/WorkTracker/daemon/project_patterns.yaml

Example

projects:
  easyAMS:
    patterns: ["*easyams*", "*easyAMS*"]
    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"

Patterns use glob syntax (* = wildcard) and are matched case-insensitively against window titles. URL patterns are checked when track_browser_urls is enabled.

How It Works

WorkTracker follows a 3-layer architecture:

Data Flow

1. Snapshots (Collector → JSONL)

Every 10 seconds, the collector writes one JSON object to today's snapshot file. Each snapshot contains:

• Active app (name, bundle ID, window title)
• All visible windows
• Input activity (keystrokes, clicks, scroll, idle times)
• Clipboard content
• Browser URL (if applicable)
• Media playback state
• Git status (if enabled)
• Calendar events (if enabled)
• Sleep/wake events

2. Sessions (Aggregator → JSON)

The aggregator groups consecutive snapshots into sessions based on app continuity and idle gaps. Each session has: start/end times, duration, app, project, intensity score, input totals.

3. Reports (Aggregator → Markdown)

Statistics are computed from sessions and rendered into Markdown tables. These serve as structured input for AI-powered narrative summaries.

Directory Structure

Launchd Services

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

Collector Deep Dive

The collector is a long-running Python daemon that takes a system snapshot every 10 seconds.

What It Captures

Input Monitoring

Uses CGEventTap in listen-only mode (cannot inject events). Runs on a separate thread with a CFRunLoop. Tracks:

• Keystroke count (and optionally plaintext content)
• Mouse clicks (left, right)
• Scroll events
• Mouse travel distance (pixels)

Focus Detection

Uses the Accessibility API (AXUIElementCopyAttributeValue) instead of NSWorkspace.frontmostApplication. This correctly identifies the focused app even when floating overlays (like the Claude Cowork widget) hold frontmost status.

Aggregator Deep Dive

The aggregator transforms raw snapshots into structured sessions and Markdown reports.

Execution Modes

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

Processing Pipeline

1. Load JSONL snapshots into a Pandas DataFrame
2. Flatten nested fields (active_app, input, clipboard, system, media, git)
3. Detect sessions using two-tier merging (see below)
4. Match each session to a project via pattern rules
5. Calculate statistics (time distribution, intensity, focus sessions)
6. Render Markdown report with tables
7. Run pattern learning for "Other" sessions

Session Detection

Sessions group consecutive snapshots that represent a single work context.

Two-Tier Merging

Tier 1: Same App + Small Gap (<30s)

If the same app appears within 30 seconds, snapshots are always merged. This handles rapid tab switching within browsers or editors.

Tier 2: Same App + Larger Gap

If the gap is larger but the app is the same, fuzzy title matching (Levenshtein ratio ≥0.7) determines whether to merge.

Session Split Triggers

• Different app detected
• Idle gap exceeds idle_threshold_seconds (default: 120s)
• Sleep/wake event detected
• Title similarity drops below threshold

Micro-Session Absorption

Sessions with fewer than min_session_snapshots (default: 2) are absorbed into the preceding session to reduce noise.

Pattern Learning

WorkTracker automatically learns new project patterns from unclassified ("Other") sessions.

How It Works

1. After daily aggregation, "Other" sessions are analyzed
2. Window titles and URLs are grouped by keyword/domain
3. Groups with ≥5 minutes total time become pattern suggestions
4. Suggestions are written to learned_patterns.yaml

Priority

Static patterns (project_patterns.yaml) always take precedence over learned patterns. This ensures 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"]

Special Features

Sleep/Wake Detection

Two mechanisms ensure sessions are correctly split across sleep events:

• Explicit: NSWorkspace notifications for macOS sleep/wake
• Heuristic: If a loop iteration takes >3× the expected interval, a gap record is inserted

Midnight Continuity

The daily aggregator loads the tail end of the previous day's snapshots (≥23:55) to handle sessions spanning midnight correctly.

Intensity Scoring

Each session gets an intensity score based on normalized input activity (keystrokes + clicks + scrolls relative to session duration). Displayed as 10-character bar charts in reports and dashboards.

Focus Sessions

Sessions longer than 25 minutes (configurable via focus_session_min_seconds) are tracked separately as focus sessions. Sessions >60 minutes are classified as deep work.

Browser URL Tracking

The collector reads browser history databases directly (SQLite) for Safari, Chrome, Firefox, Brave, Arc, and Edge. URLs are matched against url_patterns in project patterns for accurate classification.

Media Detection

Detects playback from Spotify, Apple Music, VLC, IINA, Podcasts (native apps) and YouTube, Netflix, Twitch, SoundCloud (browser tabs via title pattern matching). Parallel media activity is tracked alongside work sessions.