Task Tracker

Task Tracker is a local-first productivity and fitness tracker built with Flask, Jinja templates, HTMX, and CSV-backed persistence. It combines task management, time-sensitive planning, workouts, lightweight analytics, and a few optional local integrations without requiring a database.

What It Does

• manage tasks and subtasks grouped by annotation
• shortlist actionable items manually or automatically
• track Time Sensitive tasks with dates, optional times, recurrence, and a calendar strip
• sync selected Time Sensitive tasks to macOS Calendar.app
• log workouts and view cumulative calorie analytics
• keep data in daily CSV snapshots with optional mirrored backups

Quick Start

Requirements

• Python 3.9+
• pip
• optional: Playwright for browser smoke tests
• optional: Bring! credentials for shopping-list sync
• optional: macOS for Calendar sync, Notes export, startup script, and app bundle

Install

./setup.sh

Manual setup also works:

python3 -m venv .venv
./.venv/bin/python -m pip install --upgrade pip
./.venv/bin/python -m pip install -r requirements.txt

For browser smoke-test support:

./setup.sh --dev

Run

macOS and Linux

Direct Python launch:

./.venv/bin/python app.py

Startup script:

./scripts/startup.sh

The app runs at http://127.0.0.1:7463.

macOS App Bundle

On macOS you can also open Task Tracker.app after running setup.

This app bundle is currently a convenience launcher for a configured repo checkout, not a fully self-contained packaged app. In practice that means:

• run ./setup.sh first
• keep the repository files in place
• use the app bundle as an alternative to python app.py or ./scripts/startup.sh

Windows

Use direct Python launch rather than the macOS app bundle or shell scripts.

In PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python app.py

Then open http://127.0.0.1:7463.

Features

Tasks and Shortlist

• create, complete, delete, and reorder tasks
• expand and collapse subtask panels
• manually shortlist subtasks
• auto-shortlist due-soon Time Sensitive items
• persisted dark mode preference

Time Sensitive Planning

• dedicated Time Sensitive annotation
• due date and optional due time
• recurrence options: daily, every two days, weekly, biweekly, monthly
• 7-day and 28-day calendar strip views
• manual Calendar.app sync for selected items

Calendar Integration

• macOS Calendar.app integration via AppleScript
• calendar picker, including a dedicated Task Tracker calendar option
• date-only tasks default to 9:00 AM to 10:00 AM
• reminders at 30 and 5 minutes before
• completion renames linked events to [Done] ...
• deletion removes linked events

Workouts

• home workout logging with per-set tracking
• basketball logging by duration
• gym pull-ups by reps and sets
• rowing by distance
• cumulative calorie chart over time

Platform Support

macOS

Best-supported platform. This includes:

• core Flask app
• Calendar sync
• Notes export helper
• startup script
• Task Tracker.app

Windows

The core web app should run with direct Python launch. These should work or be close to working:

• tasks, subtasks, shortlist
• workouts and analytics
• Bring integration, assuming dependencies are installed

These remain macOS-specific:

• Calendar sync in services/calendar_service.py
• Notes export in scripts/maintenance/export_to_notes.py
• Task Tracker.app
• scripts/startup.sh

Linux

Similar to Windows: the core Flask app is the realistic target, while macOS-specific integrations are unavailable.

Tests

Core suite:

python3 -m pytest -q

Optional browser smoke tests:

python3 -m pytest -q tests/test_ui_smoke.py

Project Layout

Task_Tracker/
├── app.py
├── config.py
├── docs/
├── models/
├── routes/
├── scripts/
├── services/
├── static/
├── templates/
├── tests/
└── README.md

Key locations:

• models/tasks.py: task and subtask persistence and behavior
• models/workouts.py: workout persistence and calorie model
• routes/tasks.py: tasks, shortlist, time-sensitive planning, Calendar sync
• routes/workouts.py: workout routes and HTMX refresh flow
• routes/analytics.py: task and workout chart endpoints
• services/calendar_service.py: macOS Calendar bridge
• docs/plans/: roadmap and feature plans
• docs/summaries/: architecture and feature summaries
• scripts/maintenance/: one-off maintenance helpers
• scripts/recovery/: storage and sync recovery helpers

Optional Integrations

Bring! Integration

Bring! sync is routed through scripts/bring_sync.py. To configure it:

python3 scripts/setup_bring.py

Notes Export

The Notes export helper is separate from the main Flask app:

python3 scripts/maintenance/export_to_notes.py

Data Storage

The app writes daily CSV snapshots for:

• tasks
• subtasks
• workouts
• workout sets

It also supports:

• a primary data directory
• an optional mirrored backup directory
• pre-push protection against accidentally staging personal log CSVs