Install • Features • Demo • Discord • Donations

A highly customizable habit-tracker
that is wired for systematic self-improvement

^{zoomed out overview for 6 months}

Features

• Habits that happen any amount of times in any amount of days
• Intutive design for habits that happen more than once a day
• Ability to set targets, and change them on the go
• Tracking numeric values (up to 2 billion) and setting numeric targets

You can see the features explained with examples on the landing. And you can also check out the demo version.

Custom heatmaps, with all the above features

Monochromatic (github/anki-style)

 

Numeric

 

Fractured

Designed specifically to track habits that have to happen many times per period (available up to 16, then defaults to numeric):

 

Or track habits that happen once in a blue moon:

 

Combine habits into projects

All displayed in a 1-dimensional mode, which is more suitable for day-to-day tracking:

 

 

 

Skilltrees

Excellent for planning and tracking progressions:

Other things you might find useful

• Keybindings for common actions
• Two themes available: light and dark
• Desktop-focused
• A working mobile interface (browser-only, no app)
• Possible to create multiple accounts
• Drag and drop projects or habits to rearrange their order
• Tooltips with the selected period's information (available when you hover on cells)
• Habit and project names are clickable and lead to their individual pages (all links also available in the sidebar)

Installation

Currently, there are three methods available:

Docker compose with pre-built images (recommended)

First, make a directory for docker-compose's configs, then copy docker-compose.yaml and .env from this repo:

wget -O docker-compose.yaml https://raw.githubusercontent.com/Vsein/Neohabit/refs/heads/main/docker-compose.yaml

wget -O .env https://raw.githubusercontent.com/Vsein/Neohabit/refs/heads/main/.env.example

Then, edit as desired:

• .env to change the db/backend settings, and in-app settings like login behavior
• docker-compose.yaml to configure the ports, volumes, and other docker stuff

When ready, run:

docker compose up -d

In ~15 seconds, head to http://127.0.0.1:8080 (default) and check if everything's up and running.

If you encounter any issues, you can check the logs by running:

docker compose logs

By default, database is saved in the data/postgres folder of the directory you're running docker compose from

---

Docker compose and building images from source (web-hosting friendly)

Clone this repo and change to the cloned directory:

git clone https://github.com/Vsein/Neohabit.git && cd Neohabit

Copy .env.example into .env

cp .env.example .env

After that, edit the following files as desired:

• .env to change the db/backend settings, and in-app settings like login behavior
• docker-compose.yaml to configure the ports, volumes, and uncomment lines for building manually
• frontend/nginx.conf.template to adjust the servername in case you will be web-hosting

When ready, run:

docker compose up -d

In ~30 seconds, head to http://127.0.0.1:8080 (default) and check if everything's up and running.

If you encounter any issues, you can check the logs by running:

docker compose logs

Also, alternatively to simple docker compose up -d, you can force to rebuild everything:

docker compose up --build --force-recreate

---

Build and serve everything manually

Requirements:

• go
• postgresql
• npm
• python or nginx (for serving the static files)

Setting up frontend

Change into the frontend directory and install dependencies:

cd frontend && npm ci

• Build static files:

  npm run build

  Serve the static files in /dist, for example with python:

  python -m http.server 8080

• Or, run in development mode:

  npm start

Setting up backend

Change into the backend directory and install go packages

go mod download

Create a new Postgres database:

createdb neohabit_database

And modify the env vars before finally running:

JWT_SECRET="SuperSecretWOWBaz0nga5" \
PG_DSN="postgres://user:password@localhost:5432/neohabit_database?sslmode=disable" \
go run core/cmd/main.go -config core/config/config.yaml

---

Note

Given the nature of deploying projects, there's a hundred other ways of installing I haven't covered. Despite Neohabit being somewhat mature in terms of features, it's still a young self-hosted tool that I've only recently open-sourced.

It's possible for something not to run as I intended, and if it wastes your time, I'm sorry. If you figured out how to deploy Neohabit in, say k8s or Portanier, or your preferred deployment tool, feel free to propose an installation guide -- a pull request or just a discord message is fine.

---

Ultimate vision

My ultimate vision for Neohabit is to have a public, community-driven archive of habits that may be imported into your database/account, with all the needed progressions. Somewhat similar to the Anki's shared decks, except for habits. I've implemented the core feature - the habit-tracking part, but the rest of it still needs some time to come together.

For example:

• There's the tasklist section that I want to integrate with habits, so you can see which habits are due today (currently the tasks are dangling in their own section, and weren't my development focus)
• The skilltrees are implemented, but I'm aware of a couple of bugs there, and right now there's no way to start habits directly based on the skills listed in the skilltree. I may even take skilltrees as the base for importing new habits, I guess it'll be more clear in the future.
• "The blocks" page is dangling as a section in the side menu, but I think it'll just be a link to a website with all the archived skilltrees/habits.
• Contribution guides and community support/groups

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

The AGPL-3.0 applies to the entire repository, including all historical commits. Any modified versions - especially when offered as a network service or SaaS - must comply with its copyleft terms.

This license is chosen specifically so that Neohabit remains open-source forever.

Donations

BTC: bc1qkt9xge2a8h3zt65ju7qkyvh6z6qjn6kdz8tm4a

XMR: 48F86e1vigUU8jUSf3kBYNJhMGp38dKxqBhga9sLz1Lr5qM8QqXrY3g4X8uQyqh7wQKhm7MpxSsSpdp1PGvY96jh1MGwyx8

To anyone who's kind enough to donate, thank you! Neohabit's development has cost me more than I'm comfortable admitting, if not financially then just in time alone. Spreading the word and mentioning this project to your friends is also welcome and much appreciated.