Automate a lot of stuff in a Habitica party to get a better flow.
Go to file
maxmoon 041e7b89a0 initial commit 2023-01-10 18:10:05 +01:00
files initial commit 2023-01-10 18:10:05 +01:00
hbtc_pkg initial commit 2023-01-10 18:10:05 +01:00
LICENSE initial commit 2023-01-10 18:10:05 +01:00 initial commit 2023-01-10 18:10:05 +01:00 initial commit 2023-01-10 18:10:05 +01:00 initial commit 2023-01-10 18:10:05 +01:00
requirements.txt initial commit 2023-01-10 18:10:05 +01:00

Habitica Party - Quest Automation

With HP-QA it is possible to automatically initiate invitations, start quests and post useful information about the current progess in chat.


  • If no quest is running a random quest from a predefined list will be chosen (and bought, if not in inventory) to create an invitation
  • While invitation phase, members who didn't made a decision will be remembered in a chat message
  • While a quest is running, pending damage/collected items of all participating members will be shown in chat messages
  • If the mana alarm is active, all members will be mentioned, who have a full mana bar
  • If the inactivity alarm is active, members will be mentioned, who are inactive for n days
  • Force start quests after n hours the last quest ended
  • Force start quests after n% of all active members made a decision
  • Finish reminder if a quest is running for more than n hours
  • Deletion of old chat messages (decluttering)
  • A running quest (every day) is guaranteed
  • Full configurable with a config file


Install requirements

To install the necessary libraries, which are used in this Python 3 script, execute following command:

pip install -r requirements.txt

Generate config file

To generate a configuration a test run is recommended:

./ --testrun

  • The script will ask for your API credentials from Habitica (which can be found here)
  • After that it will ask for all other settings. It is recommended to use the default values (just hit enter).
  • If everything went fine, it will output the chat message in the terminal, which should be posted in the party chat.

Run the script

If the test run was successful, it is time to make a real run:


Check your party chat for the generated message and if something went wrong, just open a new issue with an explanation and I will fix bugs asap.

Install a cron job

This script should be executed every hour. For this it is recommended to install a cron job on your Linux or unix like machine with the following command:

crontab -e

Add the following line to your crons (it includes an explanation as a comment, which can be copied too):

# .---------------- minute (0 - 59)
# |  .------------- hour (0 - 23)
# |  |  .---------- day of month (1 - 31)
# |  |  |  .------- month (1 - 12) OR jan,feb,mar,apr ...
# |  |  |  |  .---- day of week (0 - 6) (Sunday=0 or 7) OR sun,mon,tue,wed,thu,fri,sat
# |  |  |  |  |
# *  *  *  *  * user-name command to be executed
57 */1 * * * /home/username/path_to_the_script/

I chose the 57th minute of every hour (*/1), because it should be executed before a full hour is reached. Most people have their custom day start at midnight and if they are still online at this time, their cron will be triggered. So it would be nice if a quest would run at this time (if all requirements are met). But the possibilities are huge. You could even execute this script every day but exclude weekends (57 */1 * * * mon,tue,wed,thu,fri) if you are in a party with people who like to make a quest break on weekends.

Update Party Description

To update the party description to show all the configuration values to all party members the party description can be updated with the following command:


It will use the template files/ and will replace all place holders with your predefined values from your config file. Change this file to your needs, because that's what your party members will see in the party description.