harsh for Mac

Harsh Taskmaster

A minimalist, command-line tool for tracking, understanding, and forging habits. Simple text files, informative graphs, zero friction. Habit tracking for geeks.

Track habits with just 3 commands: ask, log, todo.

Your data stays in human-readable text files you can edit, back up, and own forever.

Harsh lets you see your habits in a consistency graph (aka Seinfeld chart) based on your logging of the habit over time.

My hope is that it helps you get done what you're trying to get done in your life and live a better one.

More info in the launch post and the better habit tracking post.

Quick Start

Run harsh ask to create your config files, then edit ~/.config/harsh/habits:

Commands

Filtering

All commands accept optional filters:

Recording Habits

When prompted [y/n/s/⏎]: y = Yes, did it n = No, missed it (breaks streak) s = Skip (life happened, doesn't break streak) ⏎ = Leave unanswered for now

Adding Notes and Amounts

Track quantities and comments with @ and # in harsh ask:

The @ amount and # comment are optional. Use @ before # if using both.

Reading the Graph

Symbol Legend

The sparkline at the top shows daily completion percentage. The score excludes skipped habits.

Todo with Urgency

Habits File Format

Location: ~/.config/harsh/habits (or %APPDATA%harsh on Windows, override with HARSHPATH)

Frequency formats: 1 - Daily 7 or 1w - Weekly 3/7 - 3 times per 7 days (rolling window) 2/30 - Twice per month 0 - Track only (no warnings, doesn't affect score)

Optional end date:

Retire a habit by adding an end date (format: YYYY-MM-DD):

After the end date: Habit is excluded from scoring and sparklines Graph shows blank after end date Habit no longer appears in ask or todo Habit name, graph, and end marker muted Use harsh -H log to hide ended habits from log output

NB: Do not use : in habit names (it is used as delimiter in the habit files).

Log File Format

Location: ~/.config/harsh/log

Entries are appended automatically. Edit manually if needed.

Installation

Package Managers (recommended)

One-Line Install (macOS/Linux)

Distro Packages

Download from releases: DEB: sudo apt install ./harsh_.deb RPM: sudo dnf install ./harsh-.rpm APK: sudo apk add --allow-untrusted harsh-*.apk

Go Install

Shell Completion

Options

Global options:

Suppress colors for logging or piping: harsh --color never log stats

Hide ended habits from all output: harsh -H log or harsh -H log stats

JSON Output (Agents & Scripts)

Use harsh log --json for machine-readable output, suitable for AI agents (OpenClaw, Claude Code, etc.), scripts, and dashboards. The full visual consistency graph is represented as structured JSON, including 100 days of daily entry history per habit, allowing agents to detect patterns in habit performance, identify streaks and breaks, and surface insights that may not be obvious from the graph alone.

Output Structure

Key Fields

streak_status — current state of the habit's streak: