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:

Auto-tag tasks with due dates or reminder tags (+notify)
Calculate time deltas using UTC epoch conversion
Trigger notifications when time_until_due <= reminder_threshold
Remove spent reminder tags to prevent duplicates
Send critical notifications when tasks become due
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

# Standard due notification
task add "Call dentist" due:tomorrow

# Multiple reminders for important deadlines
task add "Client presentation" due:friday +remind1days +remind1hours +remind15mins

# Long-term planning
task add "Quarterly review" due:2026-04-01 +remind1months +remind1weeks

# Add/remove reminders anytime
task 42 modify +remind30mins
task 42 modify -remind1hours

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