From 3bf09fda312802d70f8641c9c1e7b34012808043 Mon Sep 17 00:00:00 2001
From: Sam Rolfe <samuelrolfe@gmail.com>
Date: Wed, 4 Mar 2026 16:18:22 +1100
Subject: [PATCH] Add readme

---
 README.md | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b67485f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,88 @@
+# Taskwarrior Notifications
+
+A native tag-based notification system for Taskwarrior with relative reminders and multi-platform delivery. Designed for NixOS and terminal-centric workflows.
+
+## Overview
+
+This project extends Taskwarrior with intelligent notifications using native tags instead of external state files. It provides relative reminders (e.g., "notify me 30 minutes before due") and delivers alerts via desktop notifications (Mako/Sway) and push notifications (ntfy) simultaneously.
+
+## Key Features
+
+- **Tag-based tracking** - No external state files; notifications tracked via Taskwarrior's native tag system (`+notify`, `+notified`)
+- **Relative reminders** - Remind at any interval: `+remind15min`, `+remind1hour`, `+remind2days`, `+remind1week`, etc.
+- **Multi-channel delivery** - Desktop notifications via `notify-send` + push notifications via ntfy server
+- **Auto-cleanup** - Notification tags automatically removed when tasks are completed or deleted
+- **5-minute polling** - systemd timer for continuous monitoring without resource overhead
+- **Stateless design** - Fully declarative, sync-friendly with Taskserver
+
+## Integration Stack
+
+| Component | Purpose |
+|-----------|---------|
+| **NixOS** | System-level declarative configuration |
+| **Home Manager** | User-level systemd services and timers |
+| **Niri** | Wayland compositor (Sway compatible) |
+| **Mako** | Notification daemon for desktop alerts |
+| **ntfy** | Self-hosted push notification server |
+| **Taskwarrior** | Task management and data storage |
+
+## Technical Overview
+
+**Architecture:** Pure Bash script leveraging Taskwarrior's export/modify interface with JSON parsing via jq
+
+**Core Logic:**
+1. Auto-tag tasks with due dates or reminder tags (`+notify`)
+2. Calculate time deltas using UTC epoch conversion
+3. Trigger notifications when `time_until_due <= reminder_threshold`
+4. Remove spent reminder tags to prevent duplicates
+5. Send critical notifications when tasks become due
+6. Clean up all notification tags on task completion
+
+**Services:**
+- `task-due-notify.service` - One-shot script execution
+- `task-due-notify.timer` - 5-minute polling interval
+
+**Dependencies:**
+- `taskwarrior` - Task database and CLI
+- `jq` - JSON parsing for task export
+- `libnotify` - Desktop notifications
+- `curl` - ntfy HTTP API calls
+
+## Usage Examples
+
+```bash
+# Standard due notification
+task add "Call dentist" due:tomorrow
+
+# Multiple reminders for important deadlines
+task add "Client presentation" due:friday +remind1day +remind1hour +remind15min
+
+# Long-term planning
+task add "Quarterly review" due:2026-04-01 +remind1month +remind1week
+
+# Add/remove reminders anytime
+task 42 modify +remind30min
+task 42 modify -remind1hour
+```
+
+## Why Terminal Users Need This
+
+Taskwarrior excels at task management but lacks native notification capabilities. This bridge enables:
+
+- **Workflow continuity** - Stay in the terminal; notifications come to you
+- **Context preservation** - Reminders carry task context without switching apps
+- **Declarative configuration** - Define notification behavior at task creation
+- **Cross-device awareness** - ntfy delivers to mobile when away from desk
+- **Zero UI friction** - No GUI apps, trays, or applets required
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `task-due-notify.sh` | Main notification script |
+| `commands.md` | Debug commands and troubleshooting |
+| `tasks_alerts.md` | Implementation plan and tag reference |
+
+---
+
+Built for NixOS • Wayland-first • Terminal-native