Todo.sh Add on Directory
Clone this wiki locally
List your Todo.sh add-ons here. Include a short description and a link to the GitHub repository or other location.
Table of Contents
- New/Enhanced Actions
- Add and do or prioritize in one step
- Archive only selected done items
- Edit in a designated text editor
- graph – Visualize done tasks – «Don’t break the chain» for todo.txt
- cd – Display directory paths
- nav – Open URLs in a web browser
- ac – Open activeCollab URLs in a web browser
- birdseye – Project progress report
- projectview – Group output by project
- paper – Print your todo list
- commit – Record state in local Git repository
- push – Record state in a remote Git repository
- pull – Update local state from remote Git repository
- sync – Sync state between local and remote Git repository
- rtm – Sync with Remember the Milk
- schedule – Work with date threshold
- view – Summarized todo items report
- lately – Report of recently completed tasks
- repeat – Mark an item done and immediately reenter it
- recur – Intelligently add recurring tasks
- ice_recur – Another recurring task action, but with much more flexibility
- google – Sync with Google Tasks
- standup – Daily standup status
- docs – Sync with Google Docs
- mit – Most Important Task tracking
- hey – a minimalist CRM
- tmsa – commands to help working with dated todo files
- revive – re-add items from archive
- again – Complete and re-add tasks, updating due and deferral dates
- top – Shows as many tasks as you can see in your terminal
- XP – print a readable guide of your accomplishments.
- pri – change the priority of several tasks at once.
- rm – remove several tasks at once.
- addr – add task with the projects and contexts of the last added task.
- lsgc – prints tasks in columns organized by context
- lsgp – prints tasks in columns organized by project
- pomodori-todo – A pomodoro counter implementation for todo.txt
- outline- Plan with an outline, sync your next actions
- note – Take notes related to tasks
- donow – Activity time tracker
- chcon – Change context
- rmf – Remove from file
- wp – A weekly planner
To learn how to install (and create) add-ons, see Creating and Installing Add-ons.
Since version 2.4, todo.sh provides
TODOTXT_FINAL_FILTER, which can be used to modify the list commands’ output.
Hide tasks containing a date threshold (
t:YYYY-MM-DD) until the specified point in the future.
-x option can be used to temporarily disable filtering and also display future tasks.
New or Enhanced Commands/Actions
add and do / add and pri in one step
This is the example detailed here: Creating Add-ons: Examples
It allows to add an item and mark it as done in one shot with the following syntax:todo.sh add x Helping colleague to install linux
It also allows to set a priority when adding an item using the following syntax:todo.sh add pri A “Need to write plugin example on Gina’s wiki”
Archive only selected done items
This allows to archive selectively one single item or a set of items matching a given keyword.
For example to archive all done items related to project1:
To archive item #17:todo.sh archive 17
Note that if the keyword is a number it is interpreted as an item number
edit: open in text editor
$TODO_DIR/todo.txt in your default text editor (
$EDITOR environment variable):
graph: Visualize done tasks
Graph displays bar charts showing the number of completed tasks per day.
As in Jerry Seinfeld’s don’t break the chain technique, active days will be colored green and therefore motivate you do be more productive.
git clone https://github.com/timpulver/todo.txt-graph.git graph
cd: display directory paths
Outputs the command necessary to change the current directory to the directory holding the todotxt files, the directory holding add-ons or the directory holding the configuiration file.
URL in browsertodo.sh add Should have a look at http://github.com/ginatrapani nav: open item’s ASAP
TODO: ‘Should have a look at http://github.com/ginatrapani ASAP’ added on line 111.todo.sh nav 111
ac: activeCollab integration
If activeCollab project/ticket info is associated with a task, open in the browser.todo.sh ac 12
commit: record state in local Git repository
Commit all changes to existing Git repository in
push: record state in remote Git repository
Push all changes in local state at
$TODO_DIR to an existing, remote Git repository.
Always pushes to origin master.
pull: update local state from remote Git repository
Fetch and merge all changes from an existing, remote Git repository into
Fetches from origin, merges from origin/master into master.
sync: sync state between local and remote Git repository
birdseye: your productivity report
A Python script
birdseye.py (called with the
birdseye action) analyzes the
done.txt files to generate a report of completed and incomplete items in every context and project. (Requires Python and both
birdseye files to run.)
paper: print your todo list
This will print your todo list:todo.sh paper
Also you can choose your printer:todo.sh paper -d ‘Canon-MP240’
projectview: sorts tasks by projects
List tasks categorized by project.
===== Projects =====
-Project1 -01 item 1 -Project2 -02 item 2 04 item 4 -Not in projects -03 item3
rtm: sync with Remember the Milk
Supports push and pull, but it still needs some work.
This will push to Remember the Milk:todo.sh rtm push
This will pull from Remember the Milk:todo.sh rtm pull
You will need a web browser to accept the
schedule: work with date threshold
Set, remove or change date threshold of an item. Works best together with the Future Tasks filter.
view: Summarized todo items report
Show todo items containing TERM, grouped by OPTION, and displayed in priority order. If no TERM provided, displays entire todo.txt. The original idea and script is derived from projectview by Paul.
$ todo.sh view project # Show todo items grouped by project
$ todo.sh view project @context # Show todo items grouped by project and filtered by @context
$ todo.sh view date +project # Show todo items grouped by date and filtered by +project
$ todo.sh view after # Show todo items grouped by date after and with today.
$ todo.sh view before # Show todo items grouped by date before and with today.
$ todo.sh view before +project # Show todo items grouped by date before and with today and filtered by +project
lately: Report of recently completed tasks
Generate a list of recently completed tasks. Per default lately lists tasks that were completed during the last seven days. With an optional argument, number of days, that can be overridden to show more or less.
$ todo.sh lately # Lists tasks completed within the last 7 days $ todo.sh lately 3 # Lists tasks completed within the last 3 days
repeat: Mark an item done and immediately reenters it.
This is useful for repeating todo items where the date entered is important. This command simply marks
the given item as done and reenters it again, optionally at a specified number of days from the completion date, or a specified number of days from the due date where this is one. Priority is not preserved.
$ todo.sh repeat 3 # Marks item 3 as done and recreates is as a new item $ todo.sh repeat 3 7 # Marks item 3 as done and recreates it 7 days from now $ todo.sh repeat 3 +7 # Marks item 3 as done and recreates it 7 days from the due date
recur: Intelligently add recurring tasks.
When run from a daily cron job (or similar scheduler), it will add tasks on appropriate days from a recur.txt file, while avoiding redundant adds of previously-added, not-yet-completed tasks.
ice_recur: Another recurring task action, but with much more flexibility
When run from a daily cron job (or similar scheduler), it will add tasks on appropriate days from a recur.txt file, while avoiding redundant adds of previously-added, not-yet-completed tasks.
You’ll notice this is just like “recur”; the difference is that ice_recur is much more flexible in terms of what sorts of schedules it can handle:
daily - (A) Runs every day; includes today daily 2 - (B) Runs every other day; includes today @2016-03-10 daily 2 - Runs every other day, starting on the day specified (which may or may not include today) weekly ; day Friday, Sunday - Runs every Friday and Saturday monthly ; day_of_month 11, 13 - Runs on the 11th and 13th of every month @2016-03-07 Weekly 2 ; day Thursday - Runs on Thursday every second week starting on the first Thursday after the day specified. @2016-03-01 Monthly 3 - Runs every 3 months starting on the day specified (so, occurs on the first day of the month; next occurence is 2016-06-01) @2016-01-04 Yearly - Runs every year starting on the day specifiod (so, occurs on the 4th of January)
google: sync with Google Tasks
Push or Pull todo items to and from Google Tasks.
$ todo.sh google pull #pulls tasks from Google $ todo.sh google push #push todo items to Google $ todo.sh google push all #push todo and done items to Google
You will need to set up Google API access to use (see project README).
standup: daily standup status
An add on implemented in ruby that generates a “report” for daily standups based on your tasks.
docs: sync with Google Docs
You can now sync your todo with Google Docs
Sharing your todos with people is now possible.
You can also sync your todos with third party tools like aNotes.
$ todo.sh docs pull #pulls todo from Google Docs $ todo.sh docs push #push todo to Google Docs $ todo.sh docs help #display help
- Google account (!) with a folder/tag chosen for todos items
- Google CL
- Install Google CL and configure oAuth by typing google docs list and following wizard.
- Then simply run pull or push, a quick wizard will ask you the name of the Google folder/tag to sync and voila!
Author: Amaury Decrême – amaury.decreme at gmail.com
Licence: GPL http://www.gnu.org/copyleft/gpl.html
mit: Most Important Task
Bash addon to help you track your Most Important Tasks.
$ todo.sh mit today go do something # use today or tomorrow to create a mit $ todo.sh mit friday stash millions # use a day of week to create a mit $ todo.sh mit mon water the garden # use an abbreviated day of week to create a mit $ todo.sh mit 2012.09.17 buy github # use specific date to create a mit $ todo.sh mit -h # get some help $ todo.sh mit # display all mits Past Due: do something @home (12) Today: fix something @work (14) $ todo.sh mit @home # display all mits in specified context Past Due: do something @home (12)
Author: Cody Buell
License: GPL http://www.gnu.org/copyleft/gpl.html
CRMhey: a minimalist
hey tells you one thing you should do regularly, but haven’t done lately.
$ todo.sh lf hey 1 @phone Mom (+1 234 567 8901) +family 2 @skype Dad +family 3 @email mentor 4 @write old flame <firstname.lastname@example.org> -- HEY: 4 of 4 tasks shown
$ todo.sh hey
37 @phone Mom (+1 234 567 8901) +family
TODO: 37 added
tmsa: commands to help working with dated todo files
Helper scripts to let you keep one todo.txt file per day, and move tasks between dated todo files. Intended for use with the cycle as described in Time Management for Systems Administrators.
$ todo.sh ls 1 Some task 2 Some other task 3 A third task -- 2013-06-11: 3 of 3 tasks shown $ todo.sh bump 1 Some task TODO: 1 bumped from 2013-06-11.txt to 2013-06-12.txt $ todo.sh lf 2013-06-12 1 Some task -- 2013-06-12: 1 of 1 tasks shown $ todo.sh lsa 1 Some other task 2 A third task 0 x 2013-06-11 Some task bumped:2013-06-12 $ todo.sh bumpall Some other task A third task TODO: all items bumped from 2013-06-11.txt to 2013-06-12.txt $ todo.sh lsf 2013-06-10.txt 1 Some task I forgot about -- 2013-06-10: 1 of 1 tasks shown $ todo.sh verify 2013-06-10.txt $ todo.sh bringforward Some task I forgot about TODO: all items bumped from 2013-06-10.txt to 2013-06-11.txt
Author: Mark Harrison
revive: re-add items from archive
Easily re-add tasks that you have previously completed back to your todo.txt list.
$ todo.sh revive 01 x 2013-06-25 My task 03 x 2013-06-28 Another task 02 x 2013-06-30 Some other task -- DONE: 3 of 3 tasks shown $ todo.sh revive 1 1 My task TODO: 1 added.
Author: Duncan Eastoe
again: Recurring tasks made easy.
again allows for easy completion and re-adding of tasks, with preserved
due dates and deferral dates (if any).
Tasks can be re-created in three different manners:
- Having any due dates and deferral dates set to today
- Having any due dates and deferral dates set to N days from today
- Having any due dates and deferral dates set to N days from their previous values
$ todo.sh again 31 31 x 2013-10-13 Test due:2013-10-14 t:2013-10-13 TODO: 31 marked as done. x 2013-10-13 Test due:2013-10-14 t:2013-10-13 TODO: /home/foobar/Dropbox/todo/todo.txt archived. 30 Test due:2013-10-13 t:2013-10-13 TODO: 30 added.
$ todo.sh again 31 10 31 x 2013-10-13 Test due:2013-10-14 t:2013-10-13 TODO: 31 marked as done. x 2013-10-13 Test due:2013-10-14 t:2013-10-13 TODO: /home/foobar/Dropbox/todo/todo.txt archived. 30 Test due:2013-10-23 t:2013-10-23 TODO: 30 added.
$ todo.sh again 31 +10 31 x 2013-10-13 Test due:2013-10-14 t:2013-10-13 TODO: 31 marked as done. x 2013-10-13 Test due:2013-10-14 t:2013-10-13 TODO: /home/foobar/Dropbox/todo/todo.txt archived. 30 Test due:2013-10-24 t:2013-10-23 TODO: 30 added.
Author: Niklas Thörne
top: see the top tasks.
works just like
list but truncates the list to fit in the terminal without scrolling or wrapping.
say you have 20 lines visible at a time in your terminal run
todo.sh top and you’ll see the top 16 tasks.
most useful when set as the default command with:
Author: Jon Knapp
XP – print a readable guide of your accomplishments.
XP prints the tasks completed on each day starting (x) number of days ago. You may also omit days on which no tasks were completed.
Example (Saturday where tasks were only completed Friday and Monday with the o option):
todo.sh xp -o 6
========================== Monday : 2013-12-02 ========================== x 2013-12-02 +ITSM some task I completed @work x 2013-12-02 +ITSM some task I completed @work x 2013-12-02 +ITSM some task I completed @work x 2013-12-02 +ITSM some task I completed @work ========================== Friday : 2013-12-06 ========================== x 2013-12-06 +ITSM some task I completed @work x 2013-12-06 +ITSM some task I completed @work x 2013-12-06 +ITSM some task I completed @work x 2013-12-06 +ITSM some task I completed @work x 2013-12-06 +ITSM some task I completed @work
Author: Chris Jones : email@example.com
pri – change the priority of several tasks at once.
pri ITEM#[, ITEM#, ITEM#, …] PRIORITY
For each ITEM#, calls command pri with priority PRIORITY.
$ todo.sh list @test 45 Another task @test 44 One task @test -- TODO: 2 of 45 tasks shown $ todo.sh pri 44 45 A 44 (A) One task @test TODO: 44 prioritized (A). 45 (A) Another task @test TODO: 45 prioritized (A).
rm – remove several tasks at once.
rm ITEM#[, ITEM#, ITEM#, …]
For each ITEM#, calls command rm. Removes blank lines by calling the archive command.
$ todo.sh list @test 45 (A) Another task @test 44 (A) One task @test -- TODO: 2 of 45 tasks shown $ todo.sh rm 44 45 44 (A) One task @test TODO: 44 deleted. 45 (A) Another task @test TODO: 45 deleted.
addr – add task with the projects and contexts of the last added task.
A helpful todo.sh command when you are adding lots of related tasks. It simply appends the tags of the most recent item to the item you add.
$ t add 'here is a a task +context +project' 59 here is a a task +context +project TODO: 59 added. $ t addr 'here is another task' Appending: +context +project 60 here is another task TODO: 60 added. 60 here is another task +context 60 here is another task +context +project
lsgp / lsgc – prints in columns organized by either context or group
A print method for todo.sh that uses the entire terminal instead of just one column. It splits up your todo.txt either by context or by project. Although not shown below, it does show line numbers next to each task so you can easily refer to them.
$ t lsgc @play @code (A) task (B) task (C) task task task task +research task task +tool task task @email @context (A) this guy (A) task +project (A) this guy +project (D) task +project this guy task +project this guy this guy this guy this guy this guy
pomodori-todo.txt – A pomodoro counter implementation for todo.txt
This plugin allows estimating pomodori, running a pomodoro countdown, and manually adding pomodori to todo items. Examples, installation instructions and a screenshot are available on the project page.
outline- Plan with an outline, sync your next actions
outline is an extension for command line [todo.text](https://github.com/ginatrapani/todo.txt-cli) that allows you to plan your projects in a tab-indented outline, and sync only the next actions with todo.txt. Actions for editing and displaying your outline, syncing outline.txt with todo.txt, and completing tasks directly from the outline, are also provided.
A next action is defined as the first subtask with no subtask of its own under 1) a root task or 2) a task tagged with a project (eg. “+project”)—unless the task or parent tree is tagged with @someday or @maybe (or as otherwise configured).
Next actions inherit the project tags and the nearest priority tag from their parent tree. Context tags (“@context”) are not inherited.
For the following outline.txt
(B) Walk the dog +dogwalk
Get a dog
Lookup animal shelters
Buy a +leash
Lookup pet stores
Lookup dog parks
Call mom @phone
get my GED
The following tasks will be synchronised with todo.txt (the id tags allow for synchronization between todo.txt, outline.txt, and done.txt despite editing):
(B) Lookup animal shelters id:1 +dogwalk (B) Lookup pet stores id:2 +dogwalk +leash Call mom @phone id:3
using the sync action
todo.sh outline sync
More actions are available for editing, displaying, and synchronizing the outline. For more information see the project page
note – Take notes related to tasks
This add-on allows to take notes related to tasks. Notes are stored in text files where you can write down any information related with the task. Just one file per task is allowed.
$ todo.sh ls 1 Cook cake for birthday party 2 Fix bicycle -- TODO: 2 of 2 tasks shown
$ todo.sh note add 1 # A note for task 1 will be created
1 Cook cake for birthday party note:cUn.txt
TODO: Note added to task 1.
Edit note? (y/n)
y # The user agrees to edit the note
$ todo.sh note show 1 # Later on, the user wants to see the content of the note for task 1 # Cook cake for birthday party A couple of cakes thar look great: http://www.terrificfantasticcakes.com/sacher http://www.evenbettercakes.com/tartadesanmarcos $ todo.sh note edit 1 # To add something else to the note
Author: Manuel J. Garrido
donow – Activity time tracker
Donow add-on allows to keep track of the total time spent on an activity
Keep track of current work
Once started, Donow reports on the stdout the current activity and the time spent on it. Each 10 minutes (configurable) a desktop notification (that can be disabled) will remind you the current running activity, to avoid to forget to stop the timer when not needed anymore.
Donow item format
When the timer is stopped using CTRL-C, donow will append a substring min:total-time-spent (being time expressed in minutes) to the activity description.
When the pattern “min:number” already exists, Donow just updates the counter.
$ todo.sh list 1 design Python interface for Todo.txt 2 write a basic description of donow addon min:5 -- TODO: 2 of 2 tasks shown $ todo.sh donow 1 Working on: design Python interface for Todo.txt [design Python interface for Todo.txt] 11 minute(s) passed^C 1 design Python interface for Todo.txt min:11 $ todo.sh donow 2 Working on: write a basic description of donow addon min:5 [write a basic description of donow addon min:5] 12 minute(s) passed^C 2 write a basic description of donow addon min:5 TODO: Replaced task with: 2 write a basic description of donow addon min:17
Author: Carlo Lobrano
chcon – Change context
Chcon allows fast replacement or deletion of the context tag (and whatever follows that in the task description).
$ todo.sh chcon 56 @office 56 upgrade servers @waiting TODO: Replaced task with: 56 upgrade servers @office $ todo.sh chcon 56 56 upgrade servers @office TODO: Replaced task with: 56 upgrade servers
Author: Kaarle Ritvanen
rm – Remove from file
Plugin for applying the “rm” action, which either removes a specified line or a term within that line, to any file in the todo directory
Usage: `todo.sh rmf FILENAME #ITEM [TERM]`
wp – A weekly planner addon
The basic idea of this planning mechanism is that on a per-week basis, we want to dedicate a certain percentage of time for various task groups. Total amount of time available for each task groups is mentioned in the allocations.conf file. This addon and its associated commands help to make sure that we spend the desired amount of time in various task