# Project pack: Habitica @ 11b3150

Facts about **Habitica** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Habitica treats your real life like a game. Habits, daily tasks and to-dos earn experience and gold for your avatar, and missed tasks cost health. You can join parties, fight monsters together and spend gold on gear. It is popular with people who find ordinary to-do lists hard to stick with.

## Version and source
- Repository: https://github.com/HabitRPG/habitica
- Pinned commit: `11b3150d90e6f93747b2649587ca7d18961d7029`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/HabitRPG/habitica/archive/11b3150d90e6f93747b2649587ca7d18961d7029.zip
- Live demo: https://habitica.com/. The official hosted app. It is free to use, with an optional subscription.
- Licence: **GPL-3.0-only**. Free to use and change. If you share your changed version with other people (give them the code or app), you must share your source code under the same licence. Using it privately for yourself or your household has no extra obligations. Some artwork is under separate Creative Commons licences, one of which forbids commercial use. Check before reusing images.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/HabitRPG/habitica bespoke-habitica
  cd bespoke-habitica
  git checkout --detach 11b3150d90e6f93747b2649587ca7d18961d7029
  # Prepare development requirements and local configuration first.
  cp config.json.example config.json
  npm install
  npm run client:install
  npm start
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  Use the free hosted app at https://habitica.com. To run your own copy, follow the 'Setting up Habitica Locally' guide in the Habitica wiki.
  ```

- Needs: Node 22, npm, and MongoDB, or Docker for the development stack
- Develop: `npm start  # and, in another terminal: npm run client:dev`
- Test: `npm test`
- Check/lint: `npm run lint`
- Stack: javascript (Node.js, Express, Vue, Mongoose, Gulp). Difficulty for a non-developer with an AI: **advanced**. A large Node and Vue code base with its own game content, sprites and a MongoDB database. Running it locally is doable; the hosted app is the easiest way to use it.

## Customisation points (settings → extend → code)
- **tasks-and-rewards** [settings]: Your own habits, dailies, to-dos, custom rewards and difficulty. → `In the app, under Tasks, Rewards and Settings`
- **parties-and-challenges** [settings]: Shared goals with family or friends. → `In the app, under Party and Challenges`
- **api** [extend]: Add tasks from scripts or shortcuts. → `Habitica API v3 (website/server/routes/api-v3) with your user ID and token`
- **content** [code]: Quests, pets, gear and their rules. → `website/common/script/content`
- **client-ui** [code]: Screens, avatars and layout. → `website/client/src`

## Must keep working
- Game balance in the content scripts, since it feeds many calculations.
- User data migrations under migrations/.
- Account and API token handling.

## Staying updatable
Prefer the hosted app and API. For code changes, keep content additions in new files and expect to rebase on upstream often.

## Data, costs and safety
- Personal data: **yes**. Stored in: A MongoDB database. Contains your goals, routines and habits, which are personal.
- Service: MongoDB (required, free locally): Stores users, tasks and groups.
- Service: Email provider (optional) (optional, usually free to a few dollars): Password resets and notifications.
- Setting `NODE_DB_URI` (**secret**: the person enters it themselves, never in chat): MongoDB connection string. May contain a password.
- Setting `BASE_URL`: The address people use to reach your copy.
- Your API token acts like a password. Never paste it into an AI chat or commit it.
- A self-hosted copy needs MongoDB. Keep it off the public internet.

---

# Customising Habitica

For most people the hosted Habitica app plus the API is enough. This guide is for running and changing your own copy.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Server routes and controllers | website/server/ (controllers/api-v3, models, libs) |
| Shared game rules and content | website/common/script/ |
| Web client | website/client/src/ |
| Database migrations and reports | migrations/ and database_reports/ |
| Dev config | config.json.example, docker-compose.yml |
| Tests | test/ |

## Use the gentlest change first

1. **Settings (no code):** tasks, rewards, parties and challenges inside the app.
2. **Extend:** the public API with your user ID and token.
3. **Code:** quests, content and screens in your own copy.

## Recipes

- **New quest:** add an entry in the quests content module and its art, then add tests in `test/content`.
- **New API route:** add a controller under `website/server/controllers/api-v3` and register it in the router.

## Running and checking your changes

- `npm test` runs lint and the main test tasks. It is slow, so run the specific `gulp test:*` task while working.
- Run the server and client together and complete a task to see experience and gold change.

## Pitfalls

- Never commit `config.json` with real secrets.
- Some art is under CC BY-NC-SA, so don't use it in a commercial product.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/habitica/11b3150/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/habitica/11b3150/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/habitica/11b3150/r2/SKILL.md)