RecurringTracker

RecurringTracker is a macOS-first local task tracker for repeating obligations, maintenance windows, and reminder-driven workflows. It combines a SwiftUI desktop app, a Python backend/CLI, and a local MCP server.

What It Does

• Tracks recurring items with rolling or fixed schedules
• Keeps a local history of item lifecycle changes
• Syncs selected items into Apple Calendar through a native EventKit bridge
• Supports both manual entry and structured import flows
• Exposes the same backend through a desktop app, CLI, and MCP tools

Why This Project Exists

This project is designed for recurring tasks that are too operational for a generic to-do list and too personal for a hosted SaaS workflow, such as:

• subscription renewals
• device maintenance windows
• document renewal deadlines
• quarterly or annual admin checklists

Features

• Native macOS app built with SwiftUI
• Local Python backend with stable JSON CLI
• Apple Calendar sync via Swift + EventKit
• Trash / restore flow and lifecycle history
• Paste-import and document-review import workflows
• Local MCP server for agent tooling

Architecture

• apps/RecurringTrackerMac/ Native macOS app built with SwiftUI on macOS 14+.
• tools/recurring_tracker/ Backend logic, JSON CLI, storage handling, and calendar bridge source.
• tools/recurring_tracker_mcp/ Local MCP server that wraps the backend for agent workflows.
• tools/recurring_tracker/tests/ Python regression tests for schedule and document-import behavior.
• examples/ Anonymized sample import files that document the public workflows without exposing private schedules.

Platform

• macOS only for the app and Apple Calendar sync
• Python 3.10+ for backend tooling
• Swift 5.9+ / macOS 14+ for the app and calendar bridge

Install

Bootstrap the local tooling from the repository root:

tools/recurring_tracker/bootstrap.sh
tools/recurring_tracker_mcp/bootstrap.sh

Quick Start

Native App

cd apps/RecurringTrackerMac
./run.sh

JSON CLI

Export current state:

.tools/recurring_tracker/.venv/bin/python tools/recurring_tracker/tracker_cli.py export-state

Documented CLI flows for public use:

• item lifecycle management
• document review import
• calendar sync
• clear calendar

MCP Server

.tools/recurring_tracker_mcp/.venv/bin/python tools/recurring_tracker_mcp/server.py

Example Data

Anonymized public examples are available here:

• examples/paste-import.txt
• examples/document-source.txt
• examples/reviewed-plan.json

The repository does not include real schedules, real Apple Calendar IDs, or local history from the development machine.

Apple Calendar Sync

Calendar sync uses a native macOS bridge built on EventKit.

• The first sync triggers the standard Calendar permission prompt.
• The bridge writes to a dedicated calendar.
• Completed items can create an archival (Completed) event while future reminders are refreshed separately.

This is intentionally macOS-only behavior.

Limitations

• The desktop app and calendar sync are macOS-only.
• Runtime state is stored in local JSON files under local/, not in a cloud service.
• Document import is optimized for timetable-style notices and review-before-import flows.
• The MCP server is local stdio only.

Privacy

• Runtime data is stored under local/, which is gitignored.
• Public examples are sanitized and use fictional maintenance scenarios.
• The repository excludes real calendar IDs, real reminder history, and personal schedules.

Screenshots

Current release screenshot:

Additional release assets can be added under docs/screenshots/ as the demo set expands.