261 lines
6.5 KiB
Markdown
261 lines
6.5 KiB
Markdown
# 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-notified` file
|
|
- **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
|
|
|
|
```bash
|
|
# 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:**
|
|
|
|
1. **Auto-tag pending tasks**
|
|
- Find tasks with due dates OR +remind* tags that don't have +notify
|
|
- Add +notify tag to them
|
|
|
|
2. **Process reminders**
|
|
- For each +remind* tag, calculate if we're within that window
|
|
- Send reminder notification
|
|
- Remove the reminder tag
|
|
|
|
3. **Process due tasks**
|
|
- Find tasks due before now without +notified
|
|
- Send due notification
|
|
- Add +notified tag
|
|
|
|
4. **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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
rm ~/.local/share/task-notified
|
|
```
|
|
**Step 3:** Run script manually to auto-tag existing tasks:
|
|
```bash
|
|
~/.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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
1. **No file corruption** - Tags are part of task database
|
|
2. **Sync-friendly** - Tags sync with taskserver
|
|
3. **Queryable** - Can filter/view by notification status
|
|
4. **Multiple reminders** - Not limited to one notification
|
|
5. **Flexible** - Add/remove reminders anytime
|
|
6. **Clean history** - Tags auto-removed, task stays in history
|
|
7. **Visible** - See notification status in task info
|
|
|
|
---
|
|
|
|
*Next agent should read this file and implement the script changes outlined above.*
|