node package manager
Love JavaScript? Your insights can make it even better. Take the 2017 JavaScript Ecosystem Survey »




Build Status Downloads Stories in Ready

Organize TODO, FIXME, HACK, etc. comments in code or any text file.

Initializing a Repository

var Repo        = require('imdone-core/lib/repository'),
    FsStore     = require('imdone-core/lib/mixins/repo-watched-fs-store');

var repo = FsStore(new Repo('path/to/my/project'));

repo.on('initialized', function() {
  // do something with the repo...
  var lists = repo.getLists();
  lists.forEach(function(list) {
    var listTasks = repo.getTasksInList(;

  var tasks = repo.getTasks();

repo.on('file.update', function(file) {
  // Do something usefull

repo.on('config.update', function() {
  // Do something usefull

Task formats

Code Style

// TODO This is a task
// TODO: This is a task
// TODO:5 This is a task

Hash Style

#TODO: This is a task
#TODO:0 This is a task
#to-do:0 This is a task

Markdown Style

[This is a task](#todo:)
[This is a task](#todo:10)

Task syntax

  • Code style tasks are intended to be used to capture existing tasks in code, so hash or markdown style should be used for new tasks
  • Code style tasks will only be detected if the list name matches a string in the code.include_lists attribute in .imdone/config.json and the file extension exists in lib/languages.js.
  • List names in code style tasks must be at least 2 uppercase letters or underscores
  • In Hash and markdown style tasks list name can be any combination of upper and lower case letters, underscores and dashes
  • In Hash and markdown style tasks the list name must be followed by a : and a number which determines sort order in the list
    • Sort numbers can be reused, in which case tasks with the same sort number will be sorted alphabetically by text.
  • In code, tasks can be any style but must be in a line or block comment
    • Code style tasks are only detected in comments for files with extensions listed in imdone-core/languages.js or the languages attribute in the .imdone/config.json
    • When a code style task is moved, all code style tasks in affected lists are rewitten as hash style tasks
  • For code and hash style tasks, the task text is terminated by the end of line
  • Task text can have todo.txt formatting but not todo.txt priority
  • Task text can have markdown formatting

todo.txt syntax

Create date

#DOING:20 2015-02-09 This task was created on 2015-02-09

Completed date

#DOING:20 x 2015-02-09 2015-02-08 This task was created on 2015-02-08 and completed on 2015-02-09

Due Date

#doing:20 This task is due on 2015-02-09 due:2015-02-09

Tags (todo.txt projects)

#doing:20 This task has a *madjs* tag +madjs


#doing:20 This task has a *madjs* context @madjs


#doing:20 This task has profile metadata profile:piascikj

Metadata links

  • Tasks with metadata can be linked to external resources like other task mgmt systems and websites
  • Add a meta attribute to .imdone/config.json
  • In this example user:piascikj would link to
  "meta": {
    "user": {
      "urlTemplate": "",
      "titleTemplate": "github profile for %s"

Things yet to be done...

  1. [Use visionmedia/dox, smartcomments/smartcomments and JSDoc for documenting the following... +doc](#TODO:)
  • Project

  • Repository

  • File

  • Task

  • List

  • Config

  • [Use gajus/gitdown for docs +doc](#BACKLOG:)