Taskwarrior Waybar Integration

A beautiful, modern integration between Taskwarrior and Waybar for managing tasks directly from your status bar.

Features

• 📋 Status Display - View up to 10 upcoming tasks sorted by due date
• 🎨 Modern Styling - Color-coded by urgency with priority indicators
• ➕ Quick Add - Add tasks with natural language due dates (5min, 1h, tomorrow)
• ✅ Easy Completion - Mark tasks as done with a simple interface
• 🔔 Smart Notifications - Get alerted 5 minutes before tasks are due
• 🕐 Human-Friendly Times - "today in 2h", "tomorrow at 14:30", "3d ago"
• 🌍 Timezone Aware - Correctly handles UTC timestamps from Taskwarrior

Screenshots

Tooltip Display

📋 Tasks (4 pending, 1 overdue)

● Project review     ⏰ today 30m ago     [overdue, high priority]
● Team meeting       📅 today in 2h15m    [due today]
  Code deployment    📅 tomorrow at 09:00
  Write documentation  in 3d

Notifications

• Proactive alerts 5 minutes before tasks are due
• Shows overdue count and upcoming tasks
• Formatted list with humanized times

Installation

Prerequisites

• Taskwarrior - Task management tool
• Waybar - Status bar for Wayland
• jq - JSON processor
• libnotify - Desktop notifications
• A terminal emulator (default: alacritty)

On Arch Linux:

sudo pacman -S task waybar jq libnotify alacritty

Quick Install

git clone https://github.com/coccor/taskwarrior-waybar.git ~/Work/taskwarrior-waybar
cd ~/Work/taskwarrior-waybar
./install.sh

The installer will:

1. Check for required dependencies
2. Install scripts to ~/.config/waybar/scripts/
3. Install systemd units for notifications
4. Enable and start the notification timer

Manual Installation

1. Copy scripts:

   cp scripts/* ~/.config/waybar/scripts/
   chmod +x ~/.config/waybar/scripts/taskwarrior-*.sh
   chmod +x ~/.config/waybar/scripts/humanize-date.sh

2. Install systemd units:

   cp systemd/* ~/.config/systemd/user/
   systemctl --user daemon-reload
   systemctl --user enable --now taskwarrior-notify.timer

3. Configure Waybar - Add to your ~/.config/waybar/config.jsonc:

   Add to modules-center, modules-left, or modules-right:

   "custom/taskwarrior-status"

   Add the module configuration:

   "custom/taskwarrior-status": {
     "format": "{icon}",
     "format-icons": {
        "default": "  ",
        "due": "  !"
     },
     "return-type": "json",
     "exec": "$HOME/.config/waybar/scripts/taskwarrior-status.sh",
     "interval": 60,
     "tooltip": true,
     "on-click": "alacritty -e bash -c '$HOME/.config/waybar/scripts/taskwarrior-add.sh'",
     "on-click-right": "alacritty -e bash -c '$HOME/.config/waybar/scripts/taskwarrior-done.sh'"
   }

4. Restart Waybar:

   pkill waybar && waybar &

Usage

Status Display

Hover over the taskwarrior icon in waybar to see:

• Number of pending and overdue tasks
• Up to 10 tasks sorted by due date
• Color-coded urgency:
  • 🔴 Red - Overdue tasks
  • 🟡 Yellow - Due today
  • 🔵 Blue - Due tomorrow
  • ⚪ Gray - Future tasks
• Priority indicators:
  • 🔴 ● High priority
  • 🟡 ● Medium priority
  • 🔵 ● Low priority

Adding Tasks

Left-click the taskwarrior icon to open the add dialog.

Enter task description and optional due date:

• 5min - Due in 5 minutes
• 1h - Due in 1 hour
• 2d - Due in 2 days
• tomorrow - Due tomorrow
• 2025-12-25 - Specific date
• Leave blank for no due date

The script automatically converts relative times (like 5min) to now+5min for Taskwarrior.

Completing Tasks

Right-click the taskwarrior icon to open the completion dialog.

• View all pending tasks
• Enter task ID to mark as done
• Press Enter (empty input) to complete the most urgent task

Notifications

Notifications are triggered automatically every 5 minutes for:

• Overdue tasks
• Tasks due within the next 5 minutes

Manage the notification service:

# Check status
systemctl --user status taskwarrior-notify.timer

# Stop notifications
systemctl --user stop taskwarrior-notify.timer

# Start notifications
systemctl --user start taskwarrior-notify.timer

# Change frequency (edit timer file)
systemctl --user edit taskwarrior-notify.timer

Scripts

taskwarrior-status.sh

Generates JSON output for waybar tooltip display.

• Queries pending tasks from Taskwarrior
• Sorts by due date
• Formats with modern styling

taskwarrior-add.sh

Interactive script for adding tasks.

• Prompts for description and due date
• Auto-converts relative times
• Validates input

taskwarrior-done.sh

Interactive script for completing tasks.

• Displays all pending tasks
• Allows selection by ID
• Default to most urgent task

taskwarrior-notify.sh

Notification daemon for due tasks.

• Checks for overdue tasks
• Checks for tasks due in next 5 minutes
• Sends desktop notifications with humanized times

humanize-date.sh

Utility for converting dates to human-readable format.

• Handles Taskwarrior ISO format (UTC)
• Timezone-aware conversion
• Natural language output

Usage:

# Taskwarrior format
humanize-date.sh "20251026T210000Z"
# Output: today in 10h22m

# Standard format
humanize-date.sh "2025-10-27 14:30:00"
# Output: tomorrow at 14:30

Customization

Change Terminal Emulator

Edit ~/.config/waybar/config.jsonc:

"on-click": "kitty -e bash -c '$HOME/.config/waybar/scripts/taskwarrior-add.sh'",
"on-click-right": "kitty -e bash -c '$HOME/.config/waybar/scripts/taskwarrior-done.sh'"

Replace alacritty with your preferred terminal (kitty, foot, gnome-terminal, etc.).

Change Colors

Edit taskwarrior-status.sh and modify the color codes:

# Overdue
foreground='#ff6b6b'

# Due today
foreground='#feca57'

# Due tomorrow
foreground='#48dbfb'

Change Update Interval

Edit ~/.config/waybar/config.jsonc:

"interval": 30,  // Update every 30 seconds

Change Notification Frequency

Edit ~/.config/systemd/user/taskwarrior-notify.timer:

OnUnitActiveSec=2min  # Check every 2 minutes instead of 5

Then reload:

systemctl --user daemon-reload
systemctl --user restart taskwarrior-notify.timer

Add Middle-Click Action

Edit ~/.config/waybar/config.jsonc:

"on-click-middle": "alacritty -e task"

Troubleshooting

Notifications not working

Check the systemd service:

systemctl --user status taskwarrior-notify.timer
systemctl --user status taskwarrior-notify.service

Check logs:

journalctl --user -u taskwarrior-notify.service -f

Test manually:

~/.config/waybar/scripts/taskwarrior-notify.sh

Waybar not updating

• Check if the script runs manually:

  ~/.config/waybar/scripts/taskwarrior-status.sh

• Restart waybar:

  pkill waybar && waybar &

• Check waybar logs for errors

Times showing incorrectly

Make sure your system timezone is set correctly:

timedatectl status

The scripts handle UTC timestamps from Taskwarrior automatically.

Tasks not appearing

Check if you have pending tasks:

task +PENDING

Check the JSON export:

task +PENDING export | jq

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Credits

Created to enhance productivity with Taskwarrior and Waybar.

Special thanks to:

• Taskwarrior team
• Waybar developers

Related Projects

• taskwarrior-tui - Terminal UI for Taskwarrior
• vit - Visual Interactive Taskwarrior
• Timewarrior - Time tracking companion to Taskwarrior

Changelog

v1.0.0 (2025-10-26)

• Initial release
• Status display with modern styling
• Quick add and completion scripts
• Smart notifications
• Humanized date/time display
• Timezone-aware timestamp handling
• Up to 10 tasks sorted by due date
• Priority indicators
• Color-coded urgency levels