Habitica: a habit tracker built as a role-playing game, and the API around it

Tasks become damage, and completing them becomes loot

Habitica describes itself as a habit-building program that treats your life like a role-playing game: you level up as you succeed, lose HP as you fail, and earn gold to buy weapons and armor. The three item types follow from that. Habits are things you score up or down on a numeric scale each day. Dailies reset on a schedule. Todos are one-off tasks that disappear when done.

The consequence of the game framing is that the failure state is visible. Missing a daily costs HP, and enough missed dailies mean death, which in the fiction costs you progress. A conventional tracker just shows an empty row. That difference is the entire product argument, and it explains both the project's appeal and why it does not suit everyone.

It is also worth being clear about what is and is not open. The repository is the web application: a Node and Express server, a MongoDB database and a Vue client, plus the mobile apps as separate repositories for Android and iOS. The hosted service at habitica.com is what a player actually signs up for, and the two are connected but not identical. A self-hosted install is a development and testing arrangement rather than a supported consumer product.

The project describes a large player base and a long history, and the last push to the repository was on 2026-09-21 on the `develop` branch, with the most recent release v5.50.4 on 2026-09-17.

Public pull requests are paused and AI-generated code is refused

Two notices sit at the very top of the README, above the project description, and both change what the repository means for anyone considering contributing.

The first states that public pull request submissions were paused as of August 4, 2026. The stated reason is a change in the tech landscape and in how the player base interacts with Habitica on various platforms. The acceptance of code-based contributions, which the project calls the Blacksmith tiers, is on pause. The codebase remains open source and publicly visible, and the README points to the contributing page on the project wiki for the details. So this is not a withdrawal of the code, and it is not a closure: it is a narrower door.

The second notice is unusual enough to quote closely. The repository prohibits the submission of code generated by large language models, AI coding assistants, or automated generation tools, and requires that all code be authored entirely by humans. AI-assisted commits are to be rejected during pull request review.

For a reader deciding whether to depend on this project, the practical read is that the code is auditable and available today, while the roadmap and incoming contributions are less predictable than the open-source badge alone suggests. Anyone planning a contribution should read the wiki page before writing anything, because the process has changed recently and the README points there rather than restating the rules.

A Docker Compose file that starts Mongo as a replica set

There is no install command in the README, because local setup is a wiki page. What the repository does provide is the compose file, which is the most informative artefact for a developer, because it reveals the service topology and one non-obvious requirement.

services:
  client:
    build:
      context: .
      dockerfile: ./Dockerfile-Dev
  server:
    build:
      context: .
      dockerfile: ./Dockerfile-Dev
  mongo:
    networks:
      - habitica
networks:
  habitica:
    driver: bridge

Three services: a client, a server and MongoDB, on a bridge network named for the project. The client runs a Vite-style dev server on port 5173 and depends on the server, the server listens on 3000 and depends on Mongo being healthy, and Mongo is the `mongo:7.0` image.

The detail that trips people up is Mongo's entrypoint. Rather than starting mongod normally, the compose file overrides it with `--bind_ip_all --replSet rs`, and the healthcheck is a shell one-liner that tries `rs.status()` and falls back to `rs.initiate()`. In other words, the database is started as a single-node replica set on first boot, and transactions depend on that. The 30 retries and 10 second interval exist to cover the initial initiate.

So a local install needs Docker Compose, and the failure mode when something is wrong is usually Mongo never reaching a healthy state. The two other compose files in the tree, `docker-compose.mongo-only.yml` and `docker-compose.mongo-test-local.yml`, cover running the database alone and running it for tests.

One repository holding the server, the client and the build

The dependency list in `package.json` describes the stack more precisely than the README does. The package version is 5.50.4, matching the most recent release tag, and the entry point is `./website/server/index.js`, which tells you the server is not at the root of the repository.

The runtime dependencies fall into recognisable groups. Express and body-parser handle HTTP, helmet sets headers, cookie-session handles sessions, jsonwebtoken and jwks-rsa handle tokens, and bcrypt handles passwords. mongoose is the Mongo driver. On the client side Vue is present with bootstrap for styling, and the build runs through gulp with gulp-babel, gulp-imagemin and gulp.spritesmith, which is a pre-2020 asset pipeline. Babel is configured through `.babelrc`, ESLint through `.eslintrc.js` with a shared eslint-config-habitrpg preset.

Three dependencies say something about the business. `amazon-payments` is there for subscription billing. `in-app-purchase` is pulled from a git URL rather than the registry, and so is `moment-recur`, pinned to a commit, which is what gives Habitica its recurring-task scheduling. bullmq and ioredis cover background jobs.

Deployment targets are visible too: a `Procfile` and `.buildpacks` for PaaS, `kubernetes/`, a `Dockerfile-Dev`, `.ebextensions/` for Elastic Beanstalk, and `migrations/` plus `database_reports/` for schema work. The `.nvmrc` pins the Node version, which is the file to check first when a build behaves differently on your machine.

The API is the real integration surface, and it is actively tuned

The README has one paragraph aimed squarely at developers, and it is about the API rather than the game. Third-party tool authors are asked to review the API usage guidelines to make sure their tool is compliant and maintains the best experience for players. That is a request with a legal edge to it, since the project's licence is not a standard open-source grant and the repository points to its own LICENSE file for the terms.

The three most recent releases are all API work, which tells you where the maintainers are spending attention. v5.50.4, published 2026-09-17, allows `/content` route data to be cached. v5.50.3, on 2026-09-09, requests `lean` variants of the user object where schema functions are not needed. v5.50.2, on 2026-09-03, disallows more than 100 webhooks being added to a single account, and on the client filters out `chrome-extension` errors when logging unhandled Promise rejections.

Read together, those are performance and abuse-control changes rather than new features. Caching the content route and offering lean user objects are both ways of reducing payload size, which suggests API consumers were the bottleneck. The webhook cap is the one change with teeth: if you were planning many webhooks per account, that limit is now enforced rather than merely discouraged.

Every one of these releases also carries a locale files update credited to Weblate contributors, which is a small reminder that the same codebase serves a translated user base.

Where this is the wrong choice

The clearest wrong case is someone who finds loss mechanics aversive. A tracker that costs you HP for missing a daily is motivating for one person and punitive for another, and the game layer is not separable in the hosted product. If your response to a missed day is to close the app, the mechanic works against you rather than for you.

The second wrong case is treating the repository as a product you can deploy for your users. The compose file and the wiki setup page exist for development and testing. There is no supported consumer distribution here, the mobile clients are separate repositories, and the project is not accepting outside code contributions at the moment. Anyone planning to fork Habitica into a hosted habit product is taking on an Express and Mongo application with a large dependency surface, a gulp asset pipeline, and a contributor pool that has recently narrowed.

The third is assuming the API will stay stable. This project tunes its API for performance and enforces limits on it, and it does not publish a compatibility promise in the README. Pin a version, read the usage guidelines, and keep your integration behind something you control.

Worth noting for anyone weighing a self-hosted install: bugs are not filed as public issues. The README asks for them to be reported to an admin email address, with an admin deciding whether an issue is necessary. That keeps the tracker usable and quiet, but it also means the public repository will not tell you what is broken.

Editorial conclusion

Habitica fits two groups well: people who genuinely respond to game mechanics as a motivational structure rather than as decoration, and developers who want a gamified task API they can build a bot or client on top of. It is a poor fit as a dependency for your own product, since the open-source code and the hosted service have diverged concerns and the project is winding down outside contribution. What to verify first is the API usage guidelines, because the README asks third-party tool authors to read them and they set the terms your integration has to respect, then check whether the API version you need is still covered by the current 5.50 line.

Frequently asked questions

Official sources

1. HabitRPG/habitica on GitHub
2. Issues
3. Project website
4. README
5. Releases