6.5 KiB
6.5 KiB
Taskwarrior Notification System - Implementation Plan
Date: 2026-03-03 Status: READY TO IMPLEMENT Approach: Tag-Based Notifications with Relative Reminders
Overview
Replace the separate state file system with Taskwarrior native tags. Tasks with due dates or reminder tags get automatic notification tracking.
Key Features
- Tag-based tracking: No more
~/.local/share/task-notifiedfile - Relative reminders:
+remind1hour,+remind30min,+remind2days, etc. - Auto-cleanup: Notification tags removed when task completed
- 5-minute polling: Unchanged from current setup
- Multiple reminders: Support multiple reminder tags per task
Tag System
Core Tags
| Tag | Purpose | Auto-Added? | Auto-Removed? |
|---|---|---|---|
+notify |
Mark task for notification tracking | Yes (if due date or +remind*) | Yes (on completion) |
+notified |
Task has been notified (due time reached) | Yes (when due) | Yes (on completion) |
Reminder Tags
| Tag | Time Before Due | Example Task |
|---|---|---|
+remind5min |
5 minutes | Quick reminders |
+remind10min |
10 minutes | Short prep time |
+remind15min |
15 minutes | Meeting prep |
+remind30min |
30 minutes | Standard reminder |
+remind1hour |
1 hour | Important tasks |
+remind2hours |
2 hours | Preparation needed |
+remind4hours |
4 hours | Workday planning |
+remind8hours |
8 hours | Next-day prep |
+remind12hours |
12 hours | Half-day warning |
+remind1day |
1 day | Daily planning |
+remind2days |
2 days | Medium-term tasks |
+remind3days |
3 days | Project deadlines |
+remind1week |
1 week | Long-term planning |
+remind2weeks |
2 weeks | Monthly reviews |
+remind3weeks |
3 weeks | Quarterly prep |
+remind1month |
1 month | Annual planning |
Workflow
1. Task Creation
# Standard task - gets +notify automatically
task add "Call dentist" due:tomorrow
# Task with reminders
task add "Client meeting" due:friday +remind1day +remind1hour +remind15min
# Long-term project
task add "Quarterly report" due:2026-04-01 +remind1month +remind1week
2. Notification Lifecycle
Task Created
↓
Auto-add +notify (if due date or +remind* present)
↓
Every 5 minutes script checks:
- Reminder tags within window → Send reminder, remove tag
- Due tasks without +notified → Send due notification, add +notified
↓
Task Completed
↓
Remove ALL notification tags (+notify, +notified, +remind*)
↓
Task remains in Taskwarrior history (completed tasks list)
3. Notification Types
Reminder Notifications:
- Message: "🔔 Reminder: [description] - Due in [time]"
- Urgency: normal
- Removes the triggered reminder tag
Due Notifications:
- Message: "⚠️ Task Due: [description]"
- Urgency: critical (stays visible)
- Adds +notified tag
- Also sends to ntfy push server
Script Implementation
File: /etc/nixos/home/sam/bin/task-due-notify.sh
Key Logic:
-
Auto-tag pending tasks
- Find tasks with due dates OR +remind* tags that don't have +notify
- Add +notify tag to them
-
Process reminders
- For each +remind* tag, calculate if we're within that window
- Send reminder notification
- Remove the reminder tag
-
Process due tasks
- Find tasks due before now without +notified
- Send due notification
- Add +notified tag
-
Cleanup completed tasks
- Remove all notification tags from completed/deleted tasks
- This keeps history clean but preserves task in Taskwarrior
Usage Examples
Add Tasks with Reminders
# Meeting tomorrow with advance warning
task add "Team standup" due:tomorrow9am +remind15min
# Important deadline with multiple warnings
task add "Project launch" due:friday +remind1week +remind2days +remind1hour
# Simple task - just notify when due
task add "Buy milk" due:6pm
# Add reminder to existing task
task 42 modify +remind30min
# Remove a reminder
task 42 modify -remind1hour
View Tasks
# All tasks needing notifications
task +notify list
# Tasks due now (overdue)
task due.before:now status:pending list
# Tasks with specific reminder
task +remind1hour list
# Tasks already notified
task +notified list
# All reminders (any +remind*)
task tags.has:remind list
Files Modified
1. Notification Script (MODIFIED)
Path: /etc/nixos/home/sam/bin/task-due-notify.sh
Changes:
- Remove state file dependency
- Add reminder tag processing
- Add auto-tagging logic
- Add cleanup for completed tasks
2. Home Configuration (NO CHANGES NEEDED)
Path: /etc/nixos/home/sam/home.nix
Timer and service configuration remain the same:
- 5-minute polling interval
- Same systemd service setup
3. Other Files (NO CHANGES)
- Waybar config: Unchanged
- Niri config: Unchanged
- NixOS config: Unchanged
Migration from State File
Step 1: Deploy new script Step 2: Remove old state file:
rm ~/.local/share/task-notified
Step 3: Run script manually to auto-tag existing tasks:
~/.local/bin/task-due-notify
Testing Checklist
- Add task with due date - verify +notify auto-added
- Add task with +remind30min - verify +notify auto-added
- Wait for reminder - verify notification sent, tag removed
- Wait for due time - verify notification sent, +notified added
- Complete task - verify all notification tags removed
- Check ntfy still receives push notifications
- Verify no duplicate notifications
Commands Reference
# Manual script run
~/.local/bin/task-due-notify
# Check timer
systemctl --user status task-due-notify.timer
# View notified tasks
task +notified list
# View tasks with reminders
task tags.has:remind list
# Add reminder to existing task
task <id> modify +remind1hour
# Complete task
task <id> done
# View completed tasks (history preserved)
task status:completed list
Benefits Over State File System
- No file corruption - Tags are part of task database
- Sync-friendly - Tags sync with taskserver
- Queryable - Can filter/view by notification status
- Multiple reminders - Not limited to one notification
- Flexible - Add/remove reminders anytime
- Clean history - Tags auto-removed, task stays in history
- Visible - See notification status in task info
Next agent should read this file and implement the script changes outlined above.