Terminal-based task management on Linux: part 2

In part 1 of this series, we explored the conceptual foundations for an effective terminal-based task management system. Now let's get practical and implement our solution.

Our toolchain: implementation details

After considerable experimentation, I've settled on the following combination of tools that work together to create a cohesive system:

Primary components

Taskwarrior: The workhorse of our system, managing task data, deadlines, priorities, and contexts
Taskwarrior-TUI: A text-based user interface that makes Taskwarrior more approachable with visual filtering and organisation
VimWiki: A personal wiki system for Vim that lets us blend documentation and tasks
Gollum: A Git-powered wiki server providing web access to the same content
TaskWiki: The crucial integration piece that synchronises tasks between VimWiki and Taskwarrior

Task extraction from code

For code-specific tasks, we need a way to extract TODOs from source files and potentially integrate them with our main task system. Several Vim plugins can help with this:

vim-todo - Collects TODOs across your project
vim-todo-lists - Manages TODO lists with Vim

Setting up our environment

Let's walk through the setup process step by step.

Installing the core components

On Debian/Ubuntu-based systems:

# Install Taskwarrior and Gollum
sudo apt install taskwarrior ruby ruby-dev libicu-dev zlib1g-dev
sudo gem install gollum

# Install Taskwarrior TUI
cargo install taskwarrior-tui

For VimWiki and TaskWiki, add to your Vim plugin manager (I use vim-plug):

" In your .vimrc or init.vim
Plug 'vimwiki/vimwiki'
Plug 'tools-life/taskwiki'

Then run :PlugInstall in Vim to install the plugins.

Configuring Taskwarrior

Create or edit your .taskrc file in your home directory:

# Basic configuration
data.location=~/.task
search.case.sensitive=no

# Custom colour theme
include /usr/share/taskwarrior/dark-256.theme

# Custom UDA for wiki integration
uda.wiki.type=string
uda.wiki.label=Wiki Reference

The search.case.sensitive=no setting is particularly useful, allowing for more flexible searches. You can always override this for specific searches with task rc.search.case.sensitive:yes ls /searchterm/.

Enhancing VimWiki for task management

Add these functions to your .vimrc to quickly find incomplete tasks in your wiki:

function! VimwikiFindIncompleteTasks()
  lvimgrep /* \[ \]/ %:p
  lopen
endfunction

function! VimwikiFindAllIncompleteTasks()
  VimwikiSearch /* \[ \]/
  lopen
endfunction

nmap <Leader>wa :call VimwikiFindAllIncompleteTasks()<CR>
nmap <Leader>wx :call VimwikiFindIncompleteTasks()<CR>

With these mappings, <Leader>wx shows incomplete tasks in the current file, while <Leader>wa finds all incomplete tasks across your wiki.

Tip

The default leader key is `\`, so `\wa` would find all tasks, and `\wx` would find tasks in the current file. If you've set a custom leader key, use that instead.

Practical usage patterns

Now that our system is set up, let's explore how to use it effectively for different scenarios.

Creating and managing wiki-based tasks

In VimWiki, create tasks using the standard syntax:

- [ ] Complete the project proposal by Friday
- [ ] Research potential frameworks for the authentication system

These tasks will be automatically synchronised with Taskwarrior through TaskWiki. You can toggle task completion in VimWiki by placing your cursor on a task and pressing Ctrl+Space.

Working with Taskwarrior directly

For quick task creation and management from the terminal:

# Add a new task
task add priority:H due:tomorrow Pay electricity bill

# List tasks due today
task due:today

# Complete a task
task 42 done

# Add tags to a task
task 43 modify +work +client

Viewing tasks with Taskwarrior TUI

Launch the TUI interface with taskwarrior-tui for a more visual approach to task management. This provides interactive filtering and a dashboard view that many find more accessible than the command-line interface.

Integration assessment

After extensive testing, here's what works well and what needs improvement in our integrated system:

What works smoothly

Creating tasks in VimWiki that are properly synchronised to Taskwarrior
Case-insensitive searching across task descriptions
Finding and filtering tasks by various attributes
Marking tasks complete from either VimWiki or Taskwarrior

Current limitations

Task editing in Gollum doesn't reliably synchronise back to Taskwarrior
Some complex TaskWiki features require additional plugins

Advanced customisation

Custom reports in Taskwarrior

Create focused reports for different contexts:

# In .taskrc
report.work.description=Work tasks
report.work.filter=+work status:pending
report.work.sort=due+,priority-
report.work.columns=id,due.relative,description

This creates a task work command that shows only work-related tasks sorted by due date.

Wiki linking conventions

For consistent navigation in your wiki:

# Standard internal link
[Project planning](/projects/new_initiative)

# Standard external link
[Taskwarrior documentation](https://taskwarrior.org/docs/)

Note that markdown-style links don't work inside HTML blocks: <h2>[This won't work](/link)</h2>. This is a limitation of the underlying markdown parsers.

Maintenance practices

To keep your task system healthy over time:

Regular reviews

Schedule weekly reviews to process "someday" items, clear completed tasks, and ensure due dates are realistic. Friday afternoons work well for this.

Backup strategy

Your task data represents valuable information about your work and commitments. Implement a reliable backup strategy:

# Add to your crontab or as a systemd timer
rsync -az ~/.task/ ~/Dropbox/backups/taskwarrior/
git -C ~/vimwiki commit -am "Automatic backup $(date)"
git -C ~/vimwiki push

Periodic pruning

Over time, task systems accumulate completed items that can slow performance. Archive these periodically:

# Archive completed tasks older than 30 days
task rc.confirmation=no status:completed end.before:now-30days modify status:deleted

Lessons learned

After implementing this system, several insights have emerged:

Consistency is key: Use the same patterns for all tasks to build muscle memory
Be selective: Not everything deserves entry into your task system
Regular review: Without periodic review, tasks become stale and lose relevance
Progressive improvement: Refine your workflow incrementally rather than rebuilding from scratch

Important

The most crucial factor for success isn't the specific tools you choose, but the consistency with which you use them. A simple system used reliably outperforms a sophisticated one used sporadically.

Troubleshooting common issues

Task synchronisation failures

If tasks aren't synchronising properly between VimWiki and Taskwarrior:

Check that TaskWiki is properly installed
Verify your Taskwarrior configuration
Try manually refreshing with :TaskWikiBufferLoad

Missing dependencies

TaskWiki requires Python support in Vim. Check with :echo has('python3') - if it returns 0, you'll need to install a version of Vim with Python support.

Resources for further exploration

What's next?

While this system has served me well, I'm continuously exploring improvements. Future enhancements might include:

Time tracking integration
Mobile access to tasks
Better visualisation of task dependencies
More seamless synchronisation with code-based TODOs

The tools in this ecosystem are actively developed, so keep an eye on their GitHub repositories for new features and improvements.