Script for taking notes and open urls with taskwarrior
Perl Shell Makefile
Latest commit 4ca3864 Aug 5, 2016 @ValiValpas Set version number
Failed to load latest commit information.
doc Set version number Aug 5, 2016
examples Merge branch 'devel' May 5, 2013
hooks Should have checked the htmls Feb 25, 2013
scripts tasknote refinements Aug 3, 2016
AUTHORS Documentation Jul 1, 2016
Makefile Bug #76 Apr 10, 2013
NEWS Documentation Aug 5, 2016
README.markdown Documentation Jul 1, 2016
taskopen Set version number Aug 5, 2016



This perl script is an enhancement to taskwarrior, i.e. it depends on the task binary. See

It also depends on the JSON module, i.e.

  • libjson-perl on debian
  • perl-json on archlinux
  • to be continued...

The helper scripts are usually run by bash. Some of the scripts also depend on (g)awk.

What does it do?

It allows you to link almost any file, webpage or command to a taskwarrior task by adding a filepath, web-link or uri as an annotation. Text notes, images, PDF files, web addresses, spreadsheets and many other types of links can then be filtered, listed and opened by using taskopen. Some actions are sane defaults, others can be custom-configured, and everything else will use your systems mime-types to open the link.

Arbitrary commands can be used with taskopen at the CLI, acting on the link targets, enhancing listings and even executing annotations as commands.

Run 'taskopen -h' or 'man taskopen' for further details. The following sections show some (very) basic usage examples.

Basic usage

Add a task:

$ task add Example

Add an annotation which links to a file:

$ task 1 annotate -- ~/checklist.txt

(Note that the "--" instructs taskwarrior to take the following arguments as the description part without doing any parser magic. This is particularly useful to circumvent bug #819.)

Open the linked file by using the task's ID:

$ taskopen 1

Or by a filter expression (requires > taskwarrior 2.0):

$ taskopen Example

Add default notes

Inspired by Alan Bowens 'tasknote' you can add a default notes file to a task. These files will be automatically created by the task's UUID and don't require to annotate the task with a specific file path. The folder in which these files will be stored can be configured in ~/.taskopenrc.

As soon as you annotate a task with 'Notes':

$ task 1 annotate Notes can open and edit this file by:

$ taskopen 1

...which, by default, opens a file like "~/tasknotes/5727f1c7-2efe-fb6b-2bac-6ce073ba95ee.txt".

More complex example

You can also add weblinks to a task and even mix all kinds of annotations:

$ task 1 annotate
$ task 1 annotate I want to consider this
$ task 1 annotate -- ~/Documents/manual.pdf
$ taskopen 1

Please select an annotation:
   2) ~/Documents/manual.pdf
Type number: 


Installation is as easy as:

$ make PREFIX=/usr
$ make PREFIX=/usr install

Taskopen also creates a configuration file at '~/.taskopenrc' if it does not already exist.

You can also add 'DESTDIR=/path/to/dir/' to the install command.

Perl version, migration guide

Replace your taskopen binary in /usr/bin or ~/bin with ''. Be sure to install all dependencies.

The perl version is basically backwards compatible with the bash-style taskopenrc files. However, bash magic must not be used within those files, i.e. only simple 'NAME=VALUE' notations can be parsed.


Taskopen can be customised by editing your ~/.taskopenrc file, where you can set your favourite text editor and web browser for instance. Every file that is not considered a text file or URI is going to be opened with 'xdg-open', which picks the corresponding application depending on the mime time (see 'xdg-mime').

Please take a look at the manpage taskopenrc(5) for further details.


  • Arbitrary filters
  • Optional labelling for easier access
  • Execution of arbitrary commands (overriding the default command)
  • Filtering by file type
  • Batch processing and selecting multiple files from a list
  • Deleting and editing of annotations
  • Various customisation options (e.g. sorting)
  • Extensibility

Arbitrary filters

Instead of providing taskopen with an ID you can also pass arbitrary filters in taskwarrior notation, like:

$ taskopen +next


$ taskopen +bug pro:taskwarrior


You can label your annotations by using the following syntax:

$ task 1 annotate tw:
$ task 1 annotate notes: Notes

In this way, the annotations will be accessible by providing the label name as the last argument, escaped with double backslashes:

$ taskopen 1 \\notes

or even

$ taskopen pro:taskwarrior +bug \\notes


Thanks to the following:

  • Jostein Bernsten (for adding mutt support)
  • John Hammond (for OSX 10.5+ support)
  • Alan Bowen (for writing tasknote)
  • David J Patrick (for great ideas)
  • Scott Kostyshak (for usability improvements and testing)

Feel free to contribute to this project.