wj = work journal

I often have trouble maintaining long-term direction in my work. I can't remember exactly what I worked on three days ago; what I did three weeks ago is hazy at best. This makes it hard for me to keep the big picture in mind — how much time and effort I've really devoted to any particular project.

That's why I've written a command-line program to keep track of what I've done. It's called wj, which stands for work journal. It's free and open source — installation details below.

wj helps you record and summarize what you do each day, week, month, and year. At the end of each year you get a one or two page pdf summary of everything you did, expressed in a clean week-by-week list of your accomplishments.

This is my personal replacement for software-based todo lists. I like short-term todo lists that are meant to be disposed, because they help me think carefully about what I want to do in the next several hours. If the todo list isn't disposable, then the things I thought I wanted to do, but don't really, just pile up undone and build useless stress.

So wj is not a todo list — it's a done list. It's a way to get feedback without a manager. If your work is lagging, you can see it quickly using wj. If you're doing well, you can see that, too, and reward yourself.

Here's a sample screen:

To use wj, just type ./wj.py from the command line. I have a symlink set up like this:

$ sudo ln -s /path/to/my/wj.py /usr/local/bin/wj

so I can just type wj anywhere to run it. wj also has a command-line interface so it can easily be used within bash scripts or anything else that can call command-line functions (so, virtually any modern programming language). Since it's written in python, you can also import it as a python module and gain a deeper level of control over how you interact with wj — write your own interface to it, for example.


wj records a snippet of text about what you did every day, week, month, and year you use it. This is text you must enter yourself, nothing magic. It keeps these snippets organized chronologically and by time scope (day/week/month/year). It can generate a pdf for each year you use it (technically, it generates a tex file that you can turn into a pdf by running pdflatex). I've designed the pdf to capture a detailed overview of an entire year in just two pages. This pdf includes every snippet at the year, month, and week level. Imagine using wj for 10 years, and having a nicely formatted 20-page notebook with everything you've done, down to the week, for the past decade. To me, this vision is very satisfying, and I see wj as a tool to help me achieve this.

For more specific details on how to use wj, type wj -h for the command line actions, or just run wj with no parameters to enter interactive mode (screenshot above).

wj also supports two calendar modes. Gregorian is the default mode that most people use. I use a different calendar system called the 7date, which basically uses the day-of-the-year written in base 7. I could easily fill another blog post detailing the advantages of the 7date, but for now I'll be brief and simply say that it's a better system that is fully supported by wj. If you like the Gregorian dates you're used to (things like Dec 10th 2025), then there's no need to worry about the 7date at all — Gregorian is the default mode in wj.

Here's a sample pdf for my year so far. The dates on that are 7date months and weeks, so they'll just look like numbers to most people (sorry about that). wj didn't exist at the beginning of the year, so my entries start later in the year.

Design principles

wj.py is the only file you need to run wj, along with python2.6 or later. I despise the complexities that often go along with installations and dependencies, so I put everything in this one file.

All the data is kept in the directory ~/.wj. If you want to backup your data, copy this directory somewhere. It will contain one file called config, which has some comments to assist you in editing it, and one file per year you've used wj, named after the year it depicts.

wj is open source under the Apache 2 license. It is free to use and redistribute, and will remain free forever. I would be happy to have code contributions that improve it within the vision. I would like to avoid new features. Mainly I would love to see it get a little easier to use, install, and look a little better — primarily in the pdf output.


You can get wj from its github project page:


As I said above, you can run it directly by typing ./wj.py from the directory you downloaded it to, or you can create a symlink using the above command (the "sudo ln -s ..." one), and then just type wj from anywhere.


Tyler Neylon