Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
An opinionated todo-list plugin for Sublime Text editor (version 2 and 3)
Python JavaScript HTML
branch: master
Failed to load latest commit information.
icons Editing todo.ico to correct displays in Windows
messages Support relative file link for real, e.g. ./../../file/
templates Update export to html
test Added test todo with cases that should be tested before any change re…
.gitignore updated screenshot
.no-sublime-package Always extract the plugin on Package Control install.
Default (Linux).sublime-keymap
Default (OSX).sublime-keymap Add orgmode style archive close #216
Default (Windows).sublime-keymap
Default.sublime-commands Add orgmode style archive close #216
Indentation.tmPreferences Improve indentation rules
Main.sublime-menu cancelled tasks
PlainTasks (Linux).sublime-settings
PlainTasks (OSX).sublime-settings
PlainTasks (Windows).sublime-settings Added new scheme tasks-eighties-colored close #192 Fix NewCommand for ST3 to put cursor on next line if need
PlainTasks.sublime-completions Fix #198 [Add due tag & ReplaceShortDate command for it]
PlainTasks.tmLanguage Fix #198 [Add due tag & ReplaceShortDate command for it] Fix #223 (OpenLink support markdown-style and “wiki”-style)
Symbol List.tmPreferences updated screenshot
TODO.todo Export to html; slightly change tmLang for convenient export
messages.json Add install message
separator.sublime-snippet adding separator snippet
tasks-dark.hidden-tmTheme Added priority feature close #188 fix #44
tasks-eighties-colored.hidden-tmTheme Added new scheme tasks-eighties-colored close #192
tasks-eighties-dark.hidden-tmTheme Added priority feature close #188 fix #44
tasks-gray.hidden-tmTheme Added priority feature close #188 fix #44
tasks-monokai.hidden-tmTheme Added priority feature close #188 fix #44
tasks-solarized-dark.hidden-tmTheme Added priority feature close #188 fix #44
tasks-solarized-light.hidden-tmTheme Added priority feature close #188 fix #44
tasks.hidden-tmTheme Added priority feature close #188 fix #44


An opinionated todo-list plugin for Sublime Text (2 & 3) editor


To install this plugin, you have two options:

  1. If you have Package Control installed, simply search for PlainTasks to install.

  2. Clone source code to Sublime Text packages folder.

Start a new todo-list

Bring up the command palette (it’s ⌘ + shift + p in OS X and ctrl + shift + p in Windows) and type task and select Tasks: New document command.

NOTE: Save your todo files with todo, todolist, tasks or taskpaper file extensions or just name them TODO with no extension. For more portability you can use todolist.txt either as a filename or as suffix for any arbitrary filename.


NOTE: In Windows or Linux use ctrl instead of

⌘ + enter or ⌘ + i: new task

⌘ + d: toggle task as completed.

ctrl + c: toggle task as cancelled on Mac. alt + c on Windows/Linux.

⌘ + shift + a will archive the done tasks, by removing them from your list and appending them to the bottom of the file under Archive project

⌘ + shift + o will archive in Org-Mode style, removing the entire subtree after cursor and appending it to new file next to original one, e.g. if original is filename.TODO then new would be filename_archive.TODO

⌘ + shift + u will open the url under the cursor in your default browser

☐ Anything with colon at the end of the line is a project title, you can also nest projects by indenting them.

☐ You can write plain text as notes or descriptions wherever you want. Use _ or * for italic and bold just like in Markdown.

☐ You can add tags using @ sign

☐ PlainTasks comes with a simple snippet for creating separators, if you feel that your task list is becoming too long you can split it into several sections (and fold some of them) using this snippet:

-- and then tab will give you this: --- ✄ -----------------------

☐ Completion rules (ctrl+space to see list of them):

  • type t, press tab — it’ll become @today — this one is highlighted differently than other tags;
  • c, tab — @critical;
  • h, tab — @high;
  • l, tab — @low;
  • s, tab — @started — press tab again and current date will be inserted, when you’ll complete or cancel a task with such tag, you’ll know how many time has passed since start;
  • tg, tab, tab work in the same manner as s, but inserts @toggle(current date) — so you can pause and resume to get more correct result when done/cancel; each toggle tag is either pause or resume depending on its place in sequence;
  • cr, tab, tab — @created(current date);
  • d, tab — @due( )
    If you press tab again, it’ll insert current date, same for @due( 0).
    You can type short date (similar to OrgMode’s date prompt, but not the same) and then press tab to expand it into default format.
    Short date should be @due(year-month-day hour:minute)
    Dot can be used instead of hyphen, but should be consistent

    • year, month, minute, hour can be omitted:

      Notation Meaning
      @due(1) 1st day of next month always
      @due(5) 5th day of current month (or next month if current day is 5th or older)
      @due(2-3) February 3rd of current year or next one
      @due(31 23:) 31st day of current/next month at 23 hours and minutes are equal to current moment
      @due(16.1.1 1:1) January 1st of 2016 at 01:01 @due(16-01-01 01:01)
    • relative period of time starts with a plus sign or two
      +[+][number][DdWw][h:m] — number is optional as well as letter d for days or letter w for weeks.

      Notation Meaning
      @due(+) tomorrow as well as @due( +1) or @due( +1d)
      @due(+w) one week since current date, i.e. @due( +7)
      @due(+3w) 3 weeks since current date, i.e. @due( +21d)
      @due(++) one day since @created(date) if any, otherwise it is equal to @due(+)
      @due(+2:) two hours since current date
      @due(+:555) 555 minutes since current date
      @due(+2 12:) 2 days and 12 hours since current date

☐ You can create a link to a file within your project by prefixing the file name with a dot and (back)slash like: .\filename\ or ./another filename/.
The line and column can be specified by colons: .\filename:11:8.
In SublimeText 3 you can specify a symbol inside that file by using > character like: .\filename>symbol.
In SublimeText 2 you can specify a text inside that file by using inch characters like: .\filename"any text".
Pressing ctrl + o (alt + o on Windows/Linux) will open the file in Sublime and scroll to specific position if any.
In addition, Markdown and “wiki” (Org-Mode, NV, etc.) styles are supported as well, examples:

[](path ":11:8")
[](path ">symbol")
[](path "any text")
[[path::any text]]
[[path]] ":11:8"
[[path]] ">symbol"
[[path]] "any text"

☐ To convert current document to HTML, bring up the command palette ⌘ + shift + p and type Tasks: View as HTML — it will be opened in default webbrowser, so you can view and save it.

Editor Useful Tools:

☐ Use ⌘ + control + up/down (ctrl + shift + up/down on Windows) to move tasks up and down.

☐ Use ⌘ + r to see a list of projects and quickly jump between them

★ See the Tutorial for more detailed information.


PlainTasks is an opinionated plugin, which means that it is highly configured to look in a specific way, but this does not mean that you can not customize it. If you feel that something does not look right and you want to change it, you can easily do it in your user settings file.

Go to Preferences → Package Settings → PlainTasks and open Settings - User, there you can override all the default settings, to get an idea you can take a look at Settings - Default.

Here is a list of PlainTasks’ specific settings:

Setting Default Options/Description
open_tasks_bullet - ❍ ❑ ■ □ ☐ ▪ ▫ – — ≡ → › [ ]
done_tasks_bullet ✓ ☑ + [x]
cancelled_tasks_bullet x [-]
date_format (%y-%m-%d %H:%M)
done_tag true Determines whether done tasks should gain a @done tag or not
before_tasks_bullet_margin 1 Determines the number of spaces (default indent) before the task bullet
project_tag true Postfix archived task with project tag, otherwise prefix
archive_name Archive: Make sure it is the unique project name within your todo files
indent_after_task true Determines whether next line after task should be indented or not
new_on_top true How to sort archived tasks (done_tag=true and default date_format are required)
header_to_task absent (false) If true, a project title line will be converted to a task on the certain keystroke
tasks_bullet_space absent (whitespace or tab) String to place after bullet, might be any character(s)

Taskpaper Compatibility

Go to Preferences → Package Settings → PlainTasks and open Settings - User, then add these settings to the json file:

  "translate_tabs_to_spaces": false,
  "date_format": "(%y-%m-%d)",
  "taskpaper_compatible": true

Spell check

It is build-in feature of Sublime, you can toggle spell check with F6.
For convinience, you may add bullets in list of ignored words into Preferences → Settings - User, e.g.

  "ignored_words": [ "", "", "", "" ]

[BONUS] Custom todo icon

PlainTasks comes with a custom todo icon that you can find in the icons folder. You can assign it to your todo files to give them a better look and distinguish them from other plain text files. Google and find out how to assign a custom icon to a file type in your operating system.

[BONUS] Custom Statistics

Statistics of current file are represented in status-bar, based on stats_format, which is "$n/$a done ($percent%) $progress Last task @done $last" by default — as you can see it’s just a string containing special directives (see table bellow) and regular chars.

Directive Description
$o Amount of pending tasks
$d Amount of completed tasks
$c Amount of cancelled tasks
$n Sum of completed and cancelled tasks
$a Sum of all tasks
$percent Ratio of $n to $a
$progress Percent as pseudo graphics (absents if less than 10%)
$last Date of lastly completed task
{{...}} Return pending/completed/cancelled tasks which matched by regex ...;
e.g. {{@tag}} — amounts of tasks with @tag; or {{@a|@b}} — tasks with either @a or @b or both.
You may add several {{...}} to get separate stats for different tags.

So you can customise it as you like, by adding to Settings - User, e.g.

    "stats_format": "☐$o ✔$d ✘$c",

    // if you want the statistics do not include the archived tasks:
    "stats_ignore_archive": true

Copy statistics

Bring up the command palette and type Tasks: Copy Statistics.

Additional settings for progress bar

    "bar_full": "",   // any char
    "bar_empty": "", // any char

    // if you want to avoid Unicode when copy stats — you can define replacements
    // e.g. to convert ■■■■■■☐☐☐☐ to [======    ]
    "replace_stats_chars": [["", " [="], ["", "="], ["", " ] "], ["", " "]]

Introduction to PlainTasks Screencast


You can contribute on github



Copyright 2012-2013 Allen Bargi. Licensed under the MIT License

Something went wrong with that request. Please try again.