Planner, basic configuration

| emacs, planner, wickedcoolemacs

If you’re the kind of person who likes scribbling free-form tasks and
notes in your day planner, then Planner might be a good fit for you.
In this blog post, I’ll show you how to use Planner to organize the
things you need to do by the day you need to do them, check the things
you need to do, mark tasks complete, and review what you’ve finished.
I assume that you’ve already got GNU Emacs 22 installed and that
you’re comfortable with using Emacs as a text editor, although it
might not yet be your way of life. (Just you wait! Planner was the
thing that pushed me over the edge. ;) )

Set up

Here’s the bare minimum you need in order to use Planner to manage
your tasks day by day. You’ll need Planner, which is a separate
package that you can get from
. As of this writing, Planner is at version 3.41. You’ll also need
Muse, the markup engine that Planner is based on. You can get Muse
from . As of this writing, Muse is at
version 3.11.

Download the latest versions of Planner and Muse, and unpack them. If
you don’t know where to unpack them, I suggest creating an ~/elisp
directory and extracting the archives to that directory. You should
end up with two new directories: ~/elisp/planner-3.41 and

Here’s how to configure Planner:

1. Create a directory such as ~/Plans . This is where your Planner pages will be.

2. Add the following to your .emacs:

;; Load paths - change as necessary
(add-to-list 'load-path "~/elisp/planner-3.41")
(add-to-list 'load-path "~/elisp/muse-3.11/lisp")  ;; (1)

;; Basic configuration
(require 'muse-project)
(require 'planner-autoloads)
(setq planner-project "WikiPlanner")

;; Adjust this if you already have other Muse projects
(setq muse-project-alist
	 ("~/Plans"                          ;; (2)
	  :default "TaskPool"                ;; (3)
          :major-mode planner-mode
          :visit-link planner-visit-link)))

;; Some handy keyboard shortcuts
(global-set-key (kbd "C-c d") 'planner-goto)                            ;; (4)
(global-set-key (kbd "C-c t") 'planner-create-task-from-buffer)
(global-set-key (kbd "<f9> d") 'planner-goto)                     ;; (5)
(global-set-key (kbd "<f9> t") 'planner-create-task-from-buffer)
(global-set-key (kbd "<f9> <f9>") 'planner-goto-today)      ;; (6)
(global-set-key (kbd "<f9> <f8>") 'planner-goto-yesterday)  ;; (7)
(global-set-key (kbd "<f9> <f10>") 'planner-goto-tomorrow)

(plan)  ;; (8)
  • (1) The lisp/ subdirectory is added to the load-path, not the base directory.
  • (2) Change this if you put your planner projects somewhere else.
  • (3) Muse will open the default page if you open a project.
  • (4) You’ll use these two commands often, so it helps to keep them close by. You can remember them as C-c d(ate), which jumps to a Planner date, and C-c t(ask), which creates a Planner task.
  • (5) I like dedicating one of my function keys to different Planner shortcuts. “F9 d(ate)” jumps to a Planner date and F9 t(ask) creates a task.
  • (6) You’ll check today’s page frequently, so make it an easy-to-hit shortcut. I like F9 F9 because I can just tap the key twice to see my tasks and schedule.
  • (7) This pair of keyboard shortcuts make it easy to navigate through pages.
  • (8) If this line is one of the last few in your ~/.emacs, then your Planner page for the day will display every time you start Emacs. It’s a good way to remember that it exists. ;)

Evaluate the code with M-x eval-buffer, or restart Emacs. Then you’re
ready to plan!

Planner and day pages

The first thing you need to learn is how to get to day pages
quickly. Planner needs to be at least as fast as opening a paper-based
day planner and finding the right page. Here are the two keybindings
from the previous section on setting up Planner:

F9 d(ate) or C-c d planner-goto Jumps to any day’s page
F9 F9 planner-goto-today Shows today’s page

F9 d (planner-goto) is smart. You can click on a date in the calendar
that pops up, or navigate to a date and press RET. Typing in the date
is much faster. The date format is, and it understands
partial dates (mm.dd, or just dd).

For example, if the date today is December 28, 2007, here’s what

Example Result Explanation
. 2007.12.28 Today
30 2007.12.30 Which day in the current month
1.30 2007.01.30 Which day and month in the current year
2008.01.30 2008.01.30 The full date

planner-goto also understands relative dates, and this is where things
get more interesting. If you are looking at a day page, dates are
calculated based on the day you’re currently looking at, or today if
you’re not looking at a day page. This allows you to use “+2fri” to
jump to successive paydays or use -1 to see the day before the one
you’re reading. Here are some examples that will show you what you can do:

  1. Jump to the day page for December 28, 2007 with F9 d or C-c d, specifying 2007.12.28 for the date.
  2. Use F9 d +5 to jump five days ahead. You should now see the page for 2008.01.02.
  3. Use F9 d -3 to jump three days back. (2007.12.30)
  4. Use F9 d +tue to jump to the next Tuesday. (2008.01.01)
  5. Use F9 d -2fri to jump to two Fridays ago. (2007.12.21)
  6. Use F9 d +2wed2007.12.01 to jump to the second Wednesday after Dec 1, 2007. (2007.12.12). +2wed01 would have worked, too.

(If you ever find yourself using a date shortcut like the one in (6),
please e-mail me, as I put that code in just for fun. =) )

Practice jumping around to different dates using F9 d or C-c d, the
two shortcuts we set up earlier. If one of those shortcuts feels more
natural to you, go ahead and use it. (Or bind it to something else, if
you want.) While you’re opening different day pages, write a few
reminders to yourself.

The basic configuration I suggested also has some handy shortcuts for
going to the previous and next days. Press F9 F8
(planner-goto-yesterday) to go to the day before the one that’s
currently displayed, and F9 F10 (planner-goto-tomorrow) to go to the
day after the one that’s displayed. You’ll find this handy when doing
your weekly planning. The standard shortcuts are C-c C-j C-y and C-c
C-j C-t. You may find those easier to type, but they were like a game
of Twister on my tiny keyboard. (This is also the reason why I’ve
remapped most of my keybindings. I simply can’t do the
Escape-Meta-Alt-Control-Shift thing.)

So now you know how to open different day pages. You can stop here and
already have a decent, minimalist day planner, using it like a
collection of text files that just happen to have useful navigational
commands. However, with a little more structure and some handy
shortcuts, you can be even more effective at managing your tasks.

Creating tasks

Two of the keyboard shortcuts in the sample configuration are C-c t
and F9 t, both bound to planner-create-task-from-buffer. This is an
incredibly useful function, and it gets even better as you set up more
parts of Planner. The key idea behind planner-create-task-from-buffer
is that you should be able to quickly jot down a task and GET BACK TO
WORK RIGHT AWAY. No need to fiddle around with other files or dig your
planner out of your backpack. No switching to another application (at
least, if you do most of your work within Emacs). And if you set it
up, you even get hyperlinks back to whatever you were looking at,
saving you time in searching for the file you wanted to work on or the
e-mail you wanted to answer.

Try it for yourself. Use C-c t, F9 t, or M-x
planner-create-task-from-buffer to create a task. Type in the task
description. For now, accept the default date and plan page. The task
will be created on today’s page. The task will also be copied to the
TaskPool page. To view today’s page, type F9 F9. You can use TAB
(muse-next-reference) to move the cursor to the next hyperlink, and
RET to visit the link.

planner-create-task-from-buffer understands all the date shortcuts
that planner-goto does, so you can easily schedule a task for this
Saturday (+sat) or three days from now (+3). If you create a task
that’s scheduled for some other day, you can either open the day page
with F9 d (planner-goto), or review it on the TaskPool.

Okay. You’ve got day pages. You’ve got tasks. You probably want to
find out how to mark tasks as done before your growing TODO list turns
into a monster and eats you.

Marking tasks as done, pending, or cancelled

When you finish a task, go to the day page or the plan page it’s on
and use C-c C-x (planner-task-done) to mark it as finished. Think of
it as marking completed tasks with a big X. In addition to the
satisfaction of seeing completed tasks grayed and crossed out, you’ll
also see the completed tasks drop to the bottom of your task list when
you save the file. This makes it easy to see what else you need to
do. Just pick the next item off your list and keep working.

Not quite done? You can mark it as pending with C-c C-p
(planner-task-pending). You can think of it as Pending or Postponed or

Realized that you didn’t need to do it after all? Either delete the
task with M-x planner-delete-task, or mark it as cancelled with C-c
M-C-x (planner-task-cancelled). Think of C-c M-C-x as similar to C-c
C-x (planner-task-done), but even better—you’ve gotten away without
doing something. C-c M-C-x doesn’t work on all terminals, so if your
computer gets confused and marks the task as done, call M-x
planner-task-cancelled instead.

NOTE: If your task is on both a day page and a plan page, make sure
you use these Planner commands and M-x planner-edit-task-description
in order to change the task status or description, and M-x
planner-delete-task to delete the task. These commands update the
linked page as well. If not, your tasks could get out of sync.

Even with your newfound powers of Planner task management, you’ll
probably still be left with unfinished business at the end of the day.
Unfortunately, Planner does not have a M-x planner-dilate-time command,
so you’ll just have to reschedule the tasks for another day.

Rescheduling tasks

If you wrote your tasks into your calendar using a paper-based
planner, you’d have to copy unfinished tasks to the next day one by
one. This is a powerful incentive to trim your task list and keep it
short. Planner can automatically copy unfinished tasks from the
previous days onto today’s page, saving you a lot of scribbling. Do
not let this tempt you into procrastination.

If you go back to the basic configuration, you’ll notice that it ends
with one command:


This reviews the past few days of pages for unfinished tasks, carrying
them over to today’s page. By default, the past 3 days are checked,
which should be enough to get you through a blissful no-computer
weekend. If you’re in the habit of going for long spans of time
without opening Emacs (like 4 days! *gasp*), you may want to change
the line in your ~/.emacs to something like

(plan 5)        ;; Check the last 5 days

or even

(plan t)        ;; Check all days. Can be slow!

You can also call this interactively with something like C-u 5 M-x
plan, which checks the last 5 days.

plan carries unfinished tasks from previous days to today. What if you
want to trim today’s task list to a manageable size by proactively and
intentionally procrastinating things that you don’t need to do today?
That’s where planner-copy-or-move-task comes in.

To reschedule a task, move your cursor to the task on the day or plan
page. Type C-c C-c (planner-copy-or-move-task) and specify the
date. Again, planner-copy-or-move-task understands all the Planner
date shortcuts. If you reschedule a task from a day page, remember
that relative dates will be calculated based on the day page. For
example, if you’re on 2008.08.12 and you want to reschedule a task, +1
means 2008.08.13. If you reschedule a task from a plan page, dates are
relative to today.

If you want to reschedule many tasks, you might find it more
convenient to use M-x planner-copy-or-move-region. Move to the
beginning of the first task you want to move, press C-SPC to mark the
beginning of the region, move to the end of the last task you want to
move, and call M-x planner-copy-or-move-region.

Ruthlessly reschedule until your task list for today looks
manageable. A large task list can be overwhelming. It feels better to
complete everything on your task list and then add some more, than to
end each day with many unfinished tasks.


You’ve got your day pages. You’ve added and scheduled tasks. You’ve
checked them off. At the end of the week, you’re wondering where all
the time went. Just hit F9 F9 (planner-goto-today) to jump to today’s
page, and then use F9 F8 (planner-goto-yesterday) and F9 F10
(planner-goto-tomorrow) to navigate around. (See, those keybindings
were there for a reason!)

But wait, there’s more! I’ll cover projects, timeclocking, and other
Planner goodies in an intermediate article on using Planner, so stay

Random Emacs symbol: gnus-various – Group: Other Gnus options.

You can comment with Disqus or you can e-mail me at