# habitica-ios is the native Habitica client, and it has paused outside pull requests

> The Habitica iOS repository holds the native Swift client, built with SwiftGen secrets, an xcconfig layering for debug and release, CocoaPods, Realm and fastlane, and a large set of targets for widgets, intents, notifications and snapshots. The more consequential fact is procedural: the project stopped accepting code-based contributions on 2026-08-04, and it rejects code generated by language models, so the repository is now a readable reference rather than a place to send a patch.

**HabitRPG/habitica-ios** — Native iOS app for Habitica

- Repository: https://github.com/HabitRPG/habitica-ios
- Stars: 859 · Forks: 260
- Language: Swift
- License: GPL-3.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/habitrpg-habitica-ios

## Contributions are paused, and the code stays open

The first thing the README says is a process notice, and it is dated.

Public pull request submissions were paused as of August 4, 2026. The stated reason is changes in the technology and in how the player base interacts with Habitica on various platforms, and the decision was to pause the acceptance of code-based contributions, referred to as Blacksmith tiers. The README is explicit that the codebase remains open-source and publicly visible, and it points to a section of the Habitica wiki for the details.

So the project has moved from being a place you send a patch to being a place you read. That is a normal outcome for a mobile application maintained by a very small team, and the rest of the README explains why in unusually blunt terms.

The team is described as one developer and one designer for both Android and iOS, and because of that they switch back and forth for releases. While the team works on one platform, the other is put on hold, which the README says may result in a wait time for pull requests to be reviewed or for questions to be answered, and that pull requests submitted during such a period are assigned to the next Milestone.

There is a second policy worth knowing before you write a line of code here, and it is unusual. The README carries a heading for a no AI-generated code policy, and it prohibits the submission of code generated by large language models, AI coding assistants, or automated generation tools. All code must be authored entirely by humans, and AI-assisted commits are rejected during pull request reviews.

For a repository that is still being pushed to, with the last push on 2026-10-22, that combination of facts tells you what the repository is for now: a maintained codebase in public, without an open contribution door.

## The release process lives in milestones and the Help Wanted tag

What remains documented is the process, and it is worth understanding if you are working with this code for your own reasons.

All major mobile releases are organized by Milestones labelled with the release number, and the Help Wanted tag is added to any issue the maintainers feel would be okay for a contributor to work on. The README advises looking for that tag first, and explains what the absence of the tag means, namely that staff will handle it when they have the availability.

The steps for a contribution are the standard fork and branch sequence.

```bash
2. Create your feature branch: `git checkout -b my-new-feature`
3. Commit your changes: `git commit -am 'Add some feature'`
4. Push to the branch: `git push origin my-new-feature`
```

Then a pull request is created, and the README adds a detail that is easy to miss, which is to include your Habitica user ID so the contribution can be counted towards your contributor tier.

The default branch is `develop`, not a release branch, and the tags in the release history are old, with 1.11.1 from 2017 and 1.0.1 from 2015. That combination is a reminder about how mobile apps are actually shipped. The GitHub repository is where the source lives, and the version a user gets comes from the app store pipeline rather than from a tag you can check out, so the absence of recent tags says little about whether the app is current.

The repository also carries a pull request template, a `Gemfile` and `Gemfile.lock` for the Ruby tooling around the project, a `fastlane/` directory for the release automation, and several test plans, including separate ones for unit tests and UI tests.

## The local setup starts with two config files

The setup instructions are short, and they revolve around configuration rather than dependencies, which is typical of an Xcode project with a large target matrix.

The first step is copying the sample debug configuration.

```bash
$ cp sample.debug.xcconfig debug.xcconfig
```

The second is the secrets, which the README handles with SwiftGen. The tool is installed with a single command, then the example secrets file is copied and filled in, and the generator is run.

```bash
brew install swiftgen

# Replace the secrets.yml.example to secrets.yml and set your own values

swiftgen config run
```

The repository has a `swiftgen.yml` at the root and a `swiftgen-templates/` directory, which is the pair that SwiftGen reads to produce generated Swift code from the secrets file.

The README is honest about the fallback. You can run the project without setting the credentials, but the features will be limited. That is a sensible arrangement for a developer who only needs to look at the interface, and it is worth knowing before you conclude that something is broken.

The configuration layering is the other half of the setup. The tree contains `base.xcconfig`, `project.xcconfig` and `sample.debug.xcconfig`, and the `debug.xcconfig` you create locally is expected to be picked up as the debug variant. To run the app against a locally running instance of Habitica, the README says to change `CUSTOM_DOMAIN` to `localhost:3000` or whatever port your local version uses, and to set `DISABLE_SSL` to true so the URL can be configured correctly.

Those two keys are the whole story for local server work, and they are worth noting because a local instance on plain HTTP is exactly the case where the certificate check would otherwise stop you.

## A target matrix that explains the shape of the tree

The top-level entries of the repository are the best documentation of what this application contains, and the directory names describe a modern iOS app in full.

There is a `Habitica API Client/`, a `Habitica Database/`, a `Habitica Models/`, a `Habitica Notifications/` and a `Shared/` directory, which is the core of the application split along its own concerns. Around that sit the platform integration targets: `Habitica Intents/` and `Habitica IntentsUI/` for the Shortcuts and Siri surface, `Habitica Widgets/` with a matching entitlements file for the home screen widget, `Habitica Snapshots/` for the snapshot rendering, and separate `Habitica UI Tests/` and `HabiticaTests/` directories alongside three test plan files, one for unit tests, one for UI tests and one named for the full test suite.

A few loose files at the root are worth pointing out because they are the seams between the app and its platform. `DeleteAccountView.swift` is the account deletion flow, `RemoteLogger.swift` is the remote logging client, and `RegexRoute.swift` suggests routing driven by regular expressions, which fits an application whose navigation is partly driven by server-defined routes. There is also `notification_test.apns`, which is the file you point an APNs test push at.

The infrastructure files complete the picture. A `Gemfile` and `Gemfile.lock` bring in the Ruby tooling, `fastlane/` holds the release automation, `.swiftlint.yml` and `.clang-format` define the style, and there is an `importTranslations` entry for the translation workflow, which tells you the interface is localised and the strings move through a script rather than by hand.

The topics on the repository name the same stack, with cocoapods, realm, swift, objective-c and ios, and the fact that Objective-C is still listed alongside Swift is a useful signal that the codebase is not a clean rewrite.

## What the repository is for now, and what it is not for

It is worth being direct about the mismatch between what a repository like this looks like from the outside and what it is currently.

The README is written as a contribution guide. It describes the milestone process, the Help Wanted tag, the fork and branch steps, the expectation that you include your user ID, and the note that the team is small enough that it alternates between platforms. All of that text describes a project actively taking patches from outside, and then the top of the README says that as of August 4, 2026 it is not.

So a developer arriving with a patch in hand will find the route closed, and the sensible thing to do with the code is to read it. This is a real production Swift application with a wide target matrix, a generated secrets pipeline, a config layering scheme, three test plans and release automation, and those are the parts worth studying whether you intend to contribute or not.

The other use is local development against your own server, which the `CUSTOM_DOMAIN` and `DISABLE_SSL` settings exist for. If you run a modified Habitica server and want to point the app at it, the setup is documented and short.

What the repository is not for is a fork-and-contribute model, and the AI-generated code policy narrows that further. The team has said code must be authored entirely by humans and that AI-assisted commits are rejected during review, so a tool that generates a patch will be turned away at review rather than at submission. That is a stated policy of the project rather than a technical limit, and it applies no matter how the code was produced.

The licence is GPL-3.0, with the terms in the `LICENSE` file, which is the same licence the Habitica project uses and is consistent with a client that talks to a server you are also expected to run or use.

## Conclusion

habitica-ios fits a developer who wants to study a real production Swift application, or who needs to run the Habitica client against a local server while working on something adjacent to it. Skip it if you intend to contribute upstream, because public pull request submissions are paused and the project rejects code generated by language models. Verify first which branch you need, since the default is develop rather than a release branch, and confirm that your local setup has the secrets and the debug xcconfig in place before you expect the app to behave like a signed build.

## FAQ

### Why are pull requests to habitica-ios paused?

The README says public pull request submissions were paused as of August 4, 2026, due to changes in the technology and in how the player base interacts with Habitica on various platforms, which paused the acceptance of code-based contributions at the Blacksmith tiers. The codebase remains open-source and publicly visible, and the README points to the project wiki for details.

### Does habitica-ios accept code written with an AI assistant?

No. The README states a policy prohibiting the submission of code generated by large language models, AI coding assistants, or automated generation tools, and says all code must be authored entirely by humans, with AI-assisted commits rejected during pull request reviews.

### How do I set up habitica-ios for local development?

Copy the sample debug config with `cp sample.debug.xcconfig debug.xcconfig`, install swiftgen with `brew install swiftgen`, copy `secrets.yml.example` to `secrets.yml` with your own values, and run `swiftgen config run`. The README notes that the project runs without credentials but with limited features.

### How do I run the Habitica iOS app against a local server?

Change `CUSTOM_DOMAIN` in your debug xcconfig to `localhost:3000` or whatever port your local Habitica uses, and set `DISABLE_SSL` to true so the URL can be configured correctly.

### What is the licence of the habitica-ios repository?

GPL-3.0, with the licence text in the `LICENSE` file at the top level of the repository. The default branch is `develop`.

## Sources

- [HabitRPG/habitica-ios on GitHub](https://github.com/HabitRPG/habitica-ios)
- [Issues](https://github.com/HabitRPG/habitica-ios/issues)
- [License: GPL-3.0](https://github.com/HabitRPG/habitica-ios/blob/develop/LICENSE)
- [README](https://github.com/HabitRPG/habitica-ios/blob/develop/README.md)
- [Releases](https://github.com/HabitRPG/habitica-ios/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/habitrpg-habitica-ios