harsh - a minimalist CLI habit tracker

I’m happy to announce the open source release of harsh today.

Harsh is habit tracking for geeks. A simple, minimalist CLI for tracking and understanding habits. Build great habits. Break bad ones.

Why? Habits, both good and bad, make us. We are what we do habitually. And what we do habitually ends up being what we accomplish.

You can grab harsh most easily via homebrew on OSX or linux with a simple:

λ ~ brew install wakatara/tap/harsh

or on Linux via snap with:

λ ~ sudo snap install harsh

Otherwise, binaries are available in your OS and architecture of choice.

And you can find the source here if you prefer compiling your own binaries.

Why a CLI tracker?

A big revelation for me when I started tracking habits was how inconsistent I actually was despite how my brain tricked me into thinking I wasn’t. Tracking ends up being important. So, I started testing habit trackers. Mobile were good for recording on the fly, but gave no insights into patterns and were ultimately demotivating. Emacs’ org-habits mode was overly complex and finicky.

Relief came with a Rust-based CLI in habitctl about 16 months back. Simple. One file for habits tracked, one for logging, and importantly, long-arc consistency graphs (aka Seinfeld graphs) to show long term trends and problems at a glance, and to act as motivation to keep chains going. Despite submitted PRs for fixes and features to the app though, it seems to be abandonware.

So, I decided to take the core ideas and build on them, cause… open source. I also built the new app in Go as I felt it reduced the friction in using (and developing) harsh as a full Rust environment was needed to compile and use habitctl (though Rust is cool).

harsh is the result (harsh taskmaster, actually). It’s goals: simplicity, visibility, and your consistency. I’ve fixed core habitctl features and added support for skips, warnings (when you are about to break the chain), proper score calculation, and corrected sparklines graphing. I’ll be adding in comment logging and parsing shortly and have an idea about how to measure changes in habit periodicity over time (eg. you move a habit 2 days to once a week once it’s ingrained). Binaries available across major platforms to reduce barriers to adoption, and make install simple.

So, how does it work?

How do you use it? My harsh setup has ~/.config/harsh directory symlinked to Dropbox so files get versioned and backed up (please feel free to write a git hook if you want one), and I have a dedicated tmux pane in iTerm2 so I have the 100 day consistency graph view given by harsh log and harsh todo up virtually all the time. It keeps me motivated and ensures visibility with multiple glances a day when switching to do command line tasks.

I’ve shell aliased h to the harsh command so it’s even quicker with h log (h l), h todo (h t), and h ask (h a). I use one log and habit file for each year and create new ones and archive the old Jan 1 (or did this year anyway).

When I make boo-boos I can trivially edit the log file via emacs/vim/VSCode and I keep a running commented version of the habits file to explain why X went well or poorly for a habit tracked on any given day (right now, you can put in comments manually in the file and they will still parse tho I’d like to do that on the fly when recording.). The text file’s format is parsable with standard text tools for data science analysis or spreadsheet for more advanced analysis than 100 days. It’s a CLI app so it’s targeted at engineers and data scientists.

PRs and feature requests welcome though I am trying to keep the app as simple, performant, and lightweight as possible. The code is here on Github and released under an MIT license. Please discuss issues, bugs, or features in the Github issue tracker. After this initial release I’ll be refactoring the code from some great reviews I got on the initial code base as well as adding in a pair of features and testing an idea about how to track changes to the periodicity of habits over time (habits changing over time will surprise you.)

My hope is that it unambiguously improves your life and helps you, much as it did me, developing good (or breaking bad) habits. If you are finding it useful, lemme know by mention on @awws on mastodon or via mail from the blog. Would love to hear back on how you’re using it, if it’s helped, and how it might improve.