• Project: https://github.com/linuxcaffe/awesome-taskwarrior
• Issues: https://github.com/linuxcaffe/awesome-taskwarrior/issues

awesome-taskwarrior

A handy shortcut for task (tw) that features a shell mode, debug utility, and package manager for Taskwarrior extensions.

---

TL;DR

• Drop-in wrapper for task — all task commands pass through transparently
• Package manager for hooks, scripts, configs, and docs
• Interactive shell with persistent modifiers and context multiplexing
• Dot-shortcuts, context shortcuts, file attachments, auto-paging
• Self-installing, self-updating, self-contained under ~/.task/
• Taskwarrior 2.6.2 — not compatible with v3.x

---

Why this exists

Taskwarrior is powerful out of the box, but extending it means managing hook scripts, configuration snippets, documentation, and directory structures by hand. Installing someone else's hook usually means reading a README, copying files, setting permissions, editing .taskrc, and hoping nothing breaks.

tw wraps task transparently — every command you'd normally give task works identically — while adding a registry-based package manager, an interactive shell, and a growing set of shortcuts that make daily use faster.

---

Features

• Package manager Install, update, remove, and verify Taskwarrior extensions from a central registry. Each extension is self-contained and independently installable.

• Transparent wrapper tw list, tw add, tw 42 done — everything passes straight through to task. You don't give anything up by using tw instead.

• Interactive shell Persistent modifiers, readline history, context multiplexing, and shell command execution without leaving the session.

• Context multiplexing Combine multiple Taskwarrior contexts simultaneously with @+ and @-, or use one-shot overrides with @: and @_.

• Dot-shortcuts Refer to recent tasks without looking up IDs — . for last added, .. for last modified, ... for last completed, .... for last deleted.

• Auto-paging Long output can be automatically paged through less when it exceeds terminal height.

• File attachments Attach files to tasks via the ranger file browser, stored as annotations.

• Debug infrastructure Three debug levels with color-coded output, file logging, and per-session log files under ~/.task/logs/debug/.

• Shell completions Tab completion for bash, zsh, and fish — auto-generated or manually installable.

• Safe updates tw -u preflight-downloads new files before touching the old version. If anything fails, the working version stays intact.

---

Quick install

curl -fsSL https://raw.githubusercontent.com/linuxcaffe/awesome-taskwarrior/main/install.sh | bash

This installs tw to ~/.task/scripts/tw, adds the scripts directory to your PATH, and sets up documentation in ~/.task/docs/.

No Taskwarrior 2.6.2 yet (or a 3.x your distribution brought)? tw -I taskwarrior installs it: the task2 deb on Termux, a build into ~/.local on Linux, from taskwarrior-2.6. The web UI: tw -I tw-web.

Verify with:

tw -v

View the available options with

tw -h

---

Usage

As a task wrapper

Anything you'd type after task, you can type after tw:

tw list                     # same as: task list
tw add Fix login bug +work  # same as: task add ...
tw 42 done                  # same as: task 42 done

Package manager

tw -l                       # List available extensions
tw -I recurrence-overhaul   # Install an extension
tw -u recurrence-overhaul   # Update (safe: preflight staging)
tw -r recurrence-overhaul   # Remove an extension
tw -i recurrence-overhaul   # Show extension info
tw --verify recurrence-overhaul  # Verify checksums

Context shortcuts

tw @                        # List availble contexts
tw @ work                   # Switch to work context
tw @0                       # Context none (clear)
tw @?                       # Context show (details)
tw @: personal list         # One-shot: list with personal context
tw @_ next                  # One-shot: next with no context
tw @+ work                  # Add work to context multiplexing set
tw @- morning               # Remove morning from cmx set

Dot-shortcuts

tw add Fix the login bug +work
tw . annotate "See ticket #1234"    # . = last added task
tw . start

tw 42 modify priority:H
tw .. due:tomorrow                  # .. = last modified task

tw 15 done
tw ... (w. no args runs info)       # ... = last completed (by UUID)

tw ....                             # .... = last deleted (by UUID)

Interactive shell

tw -s                       # Start shell
tw> list +work              # Task commands
tw> :push +work proj:acme   # Persistent modifiers
tw +work proj:acme> next    # Modifiers applied automatically
tw +work proj:acme> !ls     # Shell commands with ! or exec
tw +work proj:acme> !!      # Repeat last shell command
tw +work proj:acme> :pop    # Remove modifiers
tw> :q                      # Quit

Pager and attachments

tw -p list                  # Auto-page long output
tw -A 42                    # Attach file to task 42 (via ranger)

Debug

tw --debug list             # Level 1: basic operations
tw --debug=2 -I myapp       # Level 2: detailed + file ops
tw --debug=3 next           # Level 3: everything + TW hooks

Logs are written to ~/.task/logs/debug/.

---

Directory structure

After installation:

~/.task/
├── hooks/                  # Taskwarrior hooks
│   ├── on-add_recurrence.py
│   └── on-exit_recurrence.py
├── scripts/                # Wrapper scripts
│   ├── tw                  # The package manager / wrapper
│   └── rr                  # Extension scripts
├── config/                 # Configuration files
│   ├── .tw_manifest        # Installation tracking
│   └── recurrence.rc       # Extension configs
├── docs/                   # README files
│   └── recurrence_README.md
└── logs/
    └── debug/              # Debug session logs

---

How it works

awesome-taskwarrior is a registry that points to extension repositories. Extension files stay in their own repos — no duplication, no sync issues.

When you install an extension:

1. tw fetches the .install script from the registry
2. The installer downloads files from the extension's own repo via curl
3. Files are placed directly where Taskwarrior expects them
4. A manifest tracks every installed file for clean removal

Each installer is standalone — it works with or without tw installed. Users can always run bash myapp.install install directly.

Updates use preflight staging: all new files are downloaded and verified in a temp directory before the old version is touched. If anything fails, the working version is restored automatically.

---

Available extensions

Run tw -l to see the current registry, or browse:

Hooks

• agenda-edate v1.1.1 — Adds an "effective date" taken from due, scheduled, wait and until, and agenda reports that sort by it
• daily-email v0.1.1 — Send a daily Taskwarrior report by email via msmtp and systemd timer
• gamify v0.2.0 — Scores what you do and what you ignore, with points, ranks and prizes
• gittw v0.3.8 — Shares ~/.task between stations through git, merging by task UUID, with a hook that commits after every change
• hledger-add v0.1.3 — Runs hledger add when a +txn or +acct task (or one starting "pay" or "buy") is done, pre-filled from the task, and annotates the task with the entry
• nb-plugins v1.3.1 — Plugins for nb: cal (a calendar), grep, send, and tw (task notes, nb tw); installs them into nb
• nbnotes v1.1.1 — Task notes in nb: a bare nb: annotation gets the task its own note, made at once, and a linked note keeps the task's status
• need-priority v0.6.3 — Replaces pri:H/M/L with pri:1-6, after Maslow's hierarchy of needs, with filters to match
• recurrence-overhaul v3.1.1 — Replaces Taskwarrior's recurrence with periodic and chained recurrences that carry due, scheduled, wait and until
• smart-nag v1.3.3 — Shows nag messages built from conditions you configure
• stop-started v1.1.0 — Stops other active tasks when a new one is started, so one task is active at a time
• subtask v1.2.5 — Turns "- [ ] ..." annotations into real dependent tasks when the parent starts, and ticks them off as the subtasks finish
• time-defaults v1.0.2 — Gives date-only due, scheduled, wait and until values a default time of day
• timelog v2.2.1 — Records task start and stop times in an hledger timeclock file
• tod-filter v0.1.2 — Defines blocks of the day and switches tag filters (context tod) to match the time
• tw2ical v0.2.0 — Export Taskwarrior tasks to VTODO .ics files for CalDAV/khal/Radicale
• tw2nb v1.5.1 — Archives finished, logged and deleted tasks to nb, with a running daily journal; a task's own note (nbnotes) is its archive
• wikitags v1.0.0 — Lets you write :tags: inline in the description when adding a task, the same as +tags

Wrappers

• annn v0.8.0 — Opens a task's annotations in your editor: add, list, label or remove them with short commands
• deps-mgmt v0.3.0 — Manages finishing and deleting tasks that have dependencies, and shows dependency trees
• events v0.4.0 — Puts the calendar's non-task entries into Taskwarrior as holidays: public holidays, moon phases, seasons, clock changes and your own events
• mobilize v0.10.4 — Sets up a station (an Android phone in Termux, or Linux) from your gittw repo, with tw-web, m-sync and task notes
• theme-select v0.6.3 — ncurses TUI for previewing and selecting Taskwarrior color themes, with per-report theme switching

Scripts

• gtk v1.2.2 — GTK GUI library and extensions for Taskwarrior, powered by YAD
• hook-ctrl v0.3.3 — A three-panel terminal dashboard to turn installed hooks, scripts and config includes on and off
• matrix-taskbot v0.2.0 — Matrix bot for Taskwarrior: query and add tasks from any Matrix client
• powerline-taskwarrior v2.0.2 — Powerline segments for Taskwarrior: context, active task, next task, pending count
• resched v1.0.0 — Review and update stale-dated tasks
• sanity-check v0.6.1 — Finds and fixes common Taskwarrior problems (overdue tasks, stale dependencies, date conflicts), a key per fix, or edit the task
• t v1.4.0 — A command-line time log: clock in and out, check status, and query periods in hledger timeclock files
• taskwarrior v2.6.2-2 — Installs Taskwarrior 2.6.2: the task2 deb on Termux, or a build into ~/.local on Linux (no sudo); a 3.x is replaced only if you say yes
• tw-tui v25.4-tw26 — Terminal UI for Taskwarrior 2.6.x: a fork of taskwarrior-tui pinned to the last version for Taskwarrior 2
• tw-web v2.0.0 — A web and phone app for Taskwarrior 2.6.2: List, Kanban, Agenda and Calendar, installable as a PWA, updated in place by tw -u
• urgency-tweaker v1.0.0 — A terminal app to understand and tune your urgency coefficients
• vit v1.4.8 — Full-screen terminal interface for Taskwarrior 2.6.x with Vim key bindings (VIT 1.x, Perl/Curses)

---

For developers

See DEVELOPERS.md for the full guide on creating extensions, the .meta file format, installer templates, and the curl-based architecture.

See CONTRIBUTING.md for contribution workflow.

The development pipeline tool make-awesome.py handles debug enhancement, installer generation, and git/registry push in a single command.

---

Project status

Active development. Core functionality is stable and in daily use.

The package manager, wrapper, shell, and context multiplexing are working. Extensions are being added to the registry as they reach stable status.

---

Metadata

• License: MIT
• Language: Python
• Requires: Taskwarrior 2.6.2, Python 3.6+, curl, bash
• Optional: ranger (for file attachments), less (for paging)
• Version: 2.7.0