habheat

Habheat

A simple terminal UI for habit tracking with Github like heat map.

• Table of contents
• Features
  • Year Selection
  • Habheat Grid
    • Create Habit
    • Remove Habit
    • Toggle Habit
    • Update Habit
• Installation
  • Binary Releases
  • Homebrew
  • Go
• Usage
• Configuration
  • Custom Theme
  • Keybindings
    • Possible Keybindings
    • Global Keybindings
    • Heathmap Grid Keybindings

Features

All data used by this application is stored locally on your device.

Year Selection

Press space to select the year. The Default option shows 12 months starting today and going backwards. For example, for July 13 2024, the grid will show 53 weeks starting from the current week to the 2023.

Habheat Grid

The grid displays colors based on the habit completion ratio. There are built-in color schemes for the grid, and you can also create your own. Each cell in the grid represents a day. You can navigate through the grid and see the habits for any day by pressing space. This will open a popup where you can edit the habits.

Create Habit

You can create a new habit by pressing n on the habit popup. It will ask for the title of the habit, after writing your title you can press enter to confirm.

Remove Habit

Press r on a habit to remove it. Be careful, as this action cannot be undone.

Toggle Habit

Press space on a habit to toggle its completion status. This will affect the color in the heat map.

Update Habit

Press u on a habit to edit its title.

Installation

Binary Releases

For Windows, Mac OS(10.12+) or Linux, you can download a binary release here.

Homebrew

The latest binary release can be installed with Homebrew:

$ brew install metagunner/habheat/habheat
$ brew install habheat

Go

go install github.com/metagunner/habheat@latest

Building requires a working golang installation, a properly set GOPATH, and $GOPATH/bin present in $PATH. It is also required to have C/C++ compiler installed (gcc/clang) as there are C dependencies in use (mattn/go-sqlite3).

Usage

Call habheat in your terminal.

$ habheat

Configuration

Default path for the config file and the database:

• Linux: ~/.config/habheat/config.yml
• MacOS: ~/Library/Application\ Support/habheat/config.yml
• Windows: %LOCALAPPDATA%\habheat\config.yml (default location, but it will also be found in %APPDATA%\habheat\config.yml

Defaults

# Config relating to the Habheat UI
gui:
    # Config relating to colors and styles.
    theme:
        # Selected heat map color scheme.
        selected: green

        # Available heat map color schemes.
        colorSchemes:
            # Color scheme name. Set this to "selected" property.
            green:
                # Value for cell that is in the future or not applicable for the year.
                invalidDayValue: '  '

                # Value for a cell with no habits.
                noHabitsValue: '  '

                # Value for a cell with no completed habits.
                zeroCompletedHabitValue: '  '

                # Color shades with ANSI codes, from less to more
                statusValues:
                    1: "\033[48;5;22m  \033[0m"
                    2: "\033[48;5;29m  \033[0m"
                    3: "\033[48;5;34m  \033[0m"
                    4: "\033[48;5;40m  \033[0m"
                    5: "\033[48;5;118m  \033[0m"

                # Value for the cursor
                cursorValue: "\033[48;5;196m  \033[0m"

            # Blue color scheme
            ice:
                invalidDayValue: '  '
                noHabitsValue: '  '
                zeroCompletedHabitValue: '  '
                statusValues:
                    1: "\033[48;5;61m  \033[0m"
                    2: "\033[48;5;67m  \033[0m"
                    3: "\033[48;5;68m  \033[0m"
                    4: "\033[48;5;74m  \033[0m"
                    5: "\033[48;5;75m  \033[0m"
                cursorValue: "\033[48;5;196m  \033[0m"

            # Purple color scheme
            purple:
                invalidDayValue: '  '
                noHabitsValue: '  '
                zeroCompletedHabitValue: '  '
                statusValues:
                    1: "\033[48;5;55m  \033[0m"
                    2: "\033[48;5;92m  \033[0m"
                    3: "\033[48;5;93m  \033[0m"
                    4: "\033[48;5;129m  \033[0m"
                    5: "\033[48;5;135m  \033[0m"
                cursorValue: "\033[48;5;196m  \033[0m"

            # Yellow color scheme
            yellow:
                invalidDayValue: '  '
                noHabitsValue: '  '
                zeroCompletedHabitValue: '  '
                statusValues:
                    1: "\033[48;5;142m  \033[0m"
                    2: "\033[48;5;178m  \033[0m"
                    3: "\033[48;5;184m  \033[0m"
                    4: "\033[48;5;220m  \033[0m"
                    5: "\033[48;5;226m  \033[0m"
                cursorValue: "\033[48;5;196m  \033[0m"

        # Border color of the focused window
        activeBorderColor:
            - green
            - bold
            
        # Border color of non-focused windows
        inactiveBorderColor:
            - default

Built-in Color Schemes

These are all the available color schemes. The default one is green. You can change the color scheme in the configuration.

gui:
    theme:
        selected: purple # The color scheme you want

Customization

The built-in color schemes use ANSI color codes to support most terminals. Depending on your terminal's capabilities, you can also use Unicode characters.

Custom Color Scheme

"Selected" property should be same with the name of the color scheme.

gui:
  theme:
    selected: custom
    colorSchemes: 
      custom:
        invalidDayValue: "🚫"
        noHabitsValue: "  "
        zeroCompletedHabitValue: "  "
        statusValues:
          1: 😭
          2: 🥺
          3: 😎
          4: 😳
          5: 🤩
        cursorValue: 🖖

Color Attributes

The available color attributes are:

Colors

• black
• red
• green
• yellow
• blue
• magenta
• cyan
• white

Modifiers

• bold
• default
• reverse # useful for high-contrast
• underline

Keybindings

Possible keybindings

Global Keybindings

Heathmap Grid Keybindings