Coding 3 by phoneix faerie-d7idtti
Comrades are Habitica contributors who create third-party tools. This includes but is not limited to: web-based tools, apps, browser extensions, and CSS templates.

Becoming a ComradeEdit

First of all, welcome to the Habitica family! As an open source project, Habitica fully welcomes anyone in our community who wants to offer their skills to build upon the Habitica experience. To help your creation roll out smoothly and to keep the divide between official and unofficial apps clear to our players, we've put together these guidelines.

Please read this whole page before starting work on your tool to ensure that you don't need to change it later. You may also want to check that a similar tool has not already been created at the Extensions, Add-Ons, and Customizations page.

You can join the Aspiring Comrades guild to share your work, get feedback, discuss ideas with fellow contributors, and get your tool tested by other players.

Our Github repositories for each platform can be used to check out our code and pull any assets you may need from them:

Asking for AssistanceEdit

For questions about using Habitica's API and writing code with it, first see Application Programming Interface which has a lot of useful tips then feel free to ask in the Aspiring Comrades guild. To ensure easy assistance, post a link to your raw code from your preferred repository (e.g., GitHub).

For questions regarding the Habitica website's CSS and modifying it with user styles using browser extensions like Stylus, ask in the Aspiring Tailors guild.

For general programming questions, there are many guilds in Habitica about Programming and Program Languages.

Rules for Third-Party Tools

The rules in this section about tool names, icons, colors, and server calls have been put together by Habitica's staff to ensure that your creation runs well and to keep the divide between official and unofficial apps clear to all Habiticans.

All third-party tools (styles, customizations, extensions, apps, etc) must follow the "Naming", "Iconography and Colors", and "Notifying Staff about your Tool" sections. Tools that use Habitica's API must also follow the "API Server Calls" section including all of its subsections.


Choosing the right name can be very important for communicating to potential users exactly what your app or extension does. We recommend being as explicit as possible to communicate the value and use of your creation.

When referencing Habitica itself, avoid altering the name of the product. Using a variation of "Habitica" for your name can confuse users and prevent them from finding your app as search engines may think it's a typo. Try names like "Habitica Chat Extension" or "Skin for Habitica".

Do not use the word "official" in your tool's name or description.

It's recommended that you choose a name different from all other known tools. Similar names are acceptable but identical ones are best avoided to prevent confusion.

Iconography and ColorsEdit

Color palette official

Habitica's official color palette, including hex color codes. Comrades are welcome to use any except the Purple colors.

When choosing logos, icons, and colors for your tool, it's important that they are sufficiently dissimilar from Habitica's own primary colors and logo. This is to help differentiate the official apps that Habitica supports from third-party supported apps. This will also help bug reports go to the correct person, should any pop up.

Habitica's official color palette is displayed in the image to the right. You can use any color from it or any colors not listed in it. However please limit your use of the several colors labelled as purple or other purple shades that are similar to them. You can use those purples to a small degree in your tool but not as one of your primary colors and not at all in your tool's logos, icons, or header.

If your app, extension, or contribution needs an icon, avoid using the Habitica's gryphon logo ("Melior") or logos that are similar to it or modifications of it.

Habitica's staff have provided a set of iOS, Android, and generic icon mock-ups that use Habitica's palette and various icons from Habitica's user interface. Anyone is free to use them. For a preview, see the image below. Go monochrome or mix and match to create a palette unique to you! Have fun!

Icon mockups for Comrades

API Server CallsEdit

This section is essential for any tool that uses Habitica's API. It is not relevant if your tool does not use the API.

The number of server calls that a third-party app makes can drastically impact the user experience of all Habitica users, regardless of whether or not they use that particular third-party app! An app that has no delay between calls or that calls the server too frequently can quickly cause major server outages. We've included some general rules here that should help make sure your app has no problems.

Rules for API CallsEdit

This section is essential for any tool that uses Habitica's API. It is not relevant if your tool does not use the API.

  • Don't allow your app to run an infinite loop of API calls where one call is immediately followed by the same one again indefinitely.
  • When API calls require some data in Habitica, add a condition that stops automatic calls if the action can no longer be completed. For example, running out of Gold when automatically buying items should make the calls stop, or not having enough Mana when automating Skills.
  • For automated scripts that run in the background (no user intervention needed) like one that automatically casts Skills until your Mana is depleted, we ask you to keep a delay of 30s between different calls, in particular POST and PUT calls that write or update data. GET calls can be made more often if needed but still with a few seconds of delay between them. Since the API calls are being made automatically and consistently, we're asking for a longer delay than a player may be able to manually initiate through acting. This is to prevent any compounding problems of too many players letting the automatic calls run.
  • If your third-party app requires you to make calls more often or if you expect many players to use your tool please contact us in advance at
  • All API calls must include an "X-Client" Header as described below.
  • If your tool will be used by anyone apart from yourself, all of its code must be reviewable. We recommend placing it in a public repository such as GitHub.

X-Client HeaderEdit

This section is essential for any tool that uses Habitica's API. It is not relevant if your tool does not use the API.

We require all third-party apps or extensions to include an "X-Client" HTTP header with every API request. The content of the header should be the name of the extension and the creator's Habitica User ID in the format "UserID-appname". Note that this is the User ID of the person who wrote the tool, not the player who is using it! An example is given below. Placing your own User ID in your tool is not a security risk for you as your User ID is a public identifier in the same way that your Username is (however you should never write your API Token in your tool as it is like a password).

If something does go wrong and Habitica staff need to troubleshoot the source, the X-Client header will help them identify requests and let them know if it is or isn't your app or extension causing the problem. They will then contact you to help you adjust your tool so that it runs without problems.

As an example, if a player with the User ID "12345678-90ab-416b-cdef-1234567890ab" writes an app called "My Habitica App", they could specify the X-Client header as shown in the sample jQuery Ajax code below. The User ID in the X-Client header would not change depending on which player was using the tool; it is always the User ID of the author of the tool.
  url: '',
  type: 'GET',
  dataType: 'json',
  cache: false,
  beforeSend: function(xhr){
    xhr.setRequestHeader('x-client', '12345678-90ab-416b-cdef-1234567890ab-MyHabiticaApp');
    xhr.setRequestHeader('x-api-user', playerUserID);
    xhr.setRequestHeader('x-api-key',  playerAPItoken);
  success: yourFunctionToProcessTheData,
  error: yourFunctionToReportAnError,

Storing Players User Ids and API TokensEdit

If you create your own database or other data store that contains other players' API Tokens, it's essential that you make it very clear that you are doing this. Make it obvious on the tool's front page and in any documentation about the tool that the tool stores User IDs and API Tokens permanently. API Tokens are like passwords and having your own store of them means that you would be able to use anyone's account as if it were your own so it's important that people can make an informed decision about whether to allow this.

This information should be also noted on the wiki page created for the tool.

Fetching Content Descriptions and ImagesEdit

If you wish to display names, description and other information regarding, pets, backgrounds, equipment etc. This information can be source from the API Call Content. Please note it has an language option which allows you to display the text in another language other than English. This is source directly from the app itself.

Images for the product can be sourced

The complete url is made up of few components.

  1. The url from above:
  2. Prefix indicating the type of image your after. For a complete list review the image names in
  3. The Key for the item your after
  4. The suffix of .png.

For example, to show Pet Egg for the Bear, the url will be:

Where each item is

  2. Pet_Egg_
  3. BearCub
  4. .png

For example the actual Pet for Base Bear will be

Remember the key will be BearCub-Base as all pets except rare always have colour associated with them.

Class Name (State Mage Instead of Wizard)Edit

Currently classes are not stated in the Content pull. Only the keys are available, so you will need to hard-code the class names from the key, currently the only one different is mage. The current key is wizard throughout the content, when the name is actually mage.

There is currently an open ticket on github here for more information

2019 Kickbacker imagesEdit

Currently the images do not follow the naming convention and require to be hard-coded. The key and the image names are as:

Content Key Image name
armor_special_ks2019 BackerOnly-Equip-MythicGryphonArmor.gif
eyewear_special_ks2019 BackerOnly-Equip-MythicGryphonVisor.gif
head_special_ks2019 BackerOnly-Equip-MythicGryphonHelm.gif
armor_special_ks2019 BackerOnly-Equip-MythicGryphonArmor.gif
shield_special_ks2019 BackerOnly-Equip-MythicGryphonShield.gif
weapon_special_ks2019 BackerOnly-Equip-MythicGryphonGlaive.gif

Notifying Staff about your ToolEdit

When you're all done and ready for your tool to go live, please fill out the Habitica 3rd Party Application Submission form with the relevant information about your app, extension, or tool. This will help Habitica's staff keep track of new third party tools, alert them about your contribution, and let them know how to reach out to you if anything goes wrong in the future.

Creating a Wiki PageEdit

Once your tool is running well, a wiki page can be created for it and linked to from Extensions, Add-Ons, and Customizations. This lets Habiticans find your tool easily. If you feel uncomfortable creating your own wiki page, then you can link your creation in the Wizards of the Wiki guild. There, the scribes will be able to create a page for you.

When creating the wiki page, please use the Template:Infobox software template to ensure information is formatted and specified correctly.

Please note that your tool should follow all relevant advice in the "Rules for Third-Party Tools" section above before the wiki page is created. Habitica's staff might temporarily remove the wiki page for any tool that needs adjustments to comply with that advice. Ask in the Aspiring Comrades guild if you need help implementing the rules!

Contributor Tier ProcessEdit

To gain a Comrade contributor tier:

  • Check that your tool follows all relevant advice in the "Rules for Third-Party Tools" section above, including the "Notifying Staff about your Tool" subsection.
  • Post to the Aspiring Comrades guild with links to:
    • the tool
    • the tool's full source code if it uses Habitica's API
    • documentation for the tool, if any
    • the tool's wiki page if one has already been created

Other Comrades might give feedback and help you tweak your tool. It's not essential for you to follow their advice but you might like to consider it. If staff or moderators ask you to make changes to the tool's code or appearance, it will probably be necessary for those changes to be made before a tier can be awarded although you are welcome to discuss their requests if you wish.

Once approved by an admin, you will be given a tier or credit towards your next tier if you already have tiers. Keep in mind that higher tiers require more work.

If you have posted about your tool to the Aspiring Comrades guild and have not had any response from staff or mods after two weeks have passed, please post a reminder there.

See AlsoEdit

Community content is available under CC-BY-SA unless otherwise noted.