Adrien MarsdenHabitApp
Documentation

How HabitApp works

Every feature in the app: what it is, the mechanism underneath it, how to use it, and what it cannot do. Anything not yet built is marked as such rather than written in the present tense. iPhone, iOS 18 or later.

Contents

The loop

What everyone gets: goals, check-ins, rewards and the lock.

Family

A parent and a child on two phones, and what passes between them.

Over time

What changes as the record accumulates.

The loop

Goals

In the app

A goal is a commitment you write down once and then get asked about, with a reward attached to keeping it.

How it works

  • There are ten slots. The limit is the design, not a plan tier — ten is roughly the number of commitments a person can actually answer for in a day.
  • A goal is either something you do (go to the gym, send the emails, study for an hour) or something you are saving toward (headphones, a trip), and the saving kind carries a price you set.
  • Each goal has a cadence: how often the app should ask about it. That figure is a ceiling, not a quota.
  • Goals sit in priority order, and the order matters when the day runs out of notification slots — see Check-ins.

How to use it

  • Add a goal from the goals sheet, name it in your own words, and set what keeping it is worth.
  • Reorder goals by dragging. The top of the list is the one that gets asked first when the schedule is tight.
  • Pause a goal instead of deleting it if you want its history kept.

Limits

Ten active goals. A paused goal does not count against the ten.

Check-ins

In the app

The app asks whether you kept a commitment, through the day, and you answer without opening the app.

How it works

  • Check-ins arrive as notifications with the answer buttons on the lock screen, so answering is one tap and never requires launching the app.
  • The cadence you set on each goal is a ceiling. Two decay inputs — how long the goal has been running and how reliably you have been answering — can only ever slow the schedule down, never speed it past what you asked for.
  • iOS caps how many notification requests an app may have pending. Rather than silently dropping the goals at the bottom of the list when that cap is hit, low-priority goals are rolled together: the highest-priority goal in a time band owns that band's notification and its body carries a "+N more" tail, and opening it shows the rest.
  • Answering honestly is the only thing that mints. A skip is not an answer and carries no penalty.

How to use it

  • Answer from the notification. Opening the app to answer is supported but is not the intended path.
  • If the prompts feel too frequent, lower the cadence on the individual goal rather than muting notifications wholesale.
  • Pin the cadence exactly where you set it if you do not want the adaptive slowdown.

Limits

The app cannot tell whether you actually went to the gym. It scores what you tell it, and the honesty of the record is the honesty of your answers.

Rewards

In the app

Keeping a commitment mints minutes of screen time on the apps you nominated, and moves money toward the thing you are saving for.

How it works

  • Two currencies. Minutes are spendable immediately on the reward apps you chose. The savings figure is a running total toward a goal you named.
  • Minutes come out of one shared pool. There are no per-app budgets and no schedules — you earned an amount, you spend it on whichever nominated app you like.
  • A lapse can carry a deduction if you set one. Deductions come off the minute ledger, and the balance is allowed to go negative, bounded at one day.
  • The rate does not change over time. What you set a goal to be worth is what it stays worth until you change it.

How to use it

  • Set what each goal is worth when you write it. If a goal is not pulling its weight after a few weeks, change the price rather than abandoning the goal.
  • Decide up front whether lapses cost anything. Many people are better served by minting less than by deducting.

Limits

The savings figure is a number the app keeps. HabitApp does not hold, move or transfer money — settling it is between you and your own bank account.

Reward apps and the shield

In the app

The apps you nominate as rewards are locked by Apple Screen Time and open only while you have minutes.

How it works

  • You pick the reward apps through Apple's own picker. The app never sees which apps you chose — Apple hands over opaque tokens, not names.
  • Locking and unlocking runs on Apple's Screen Time framework, so it holds system-wide rather than only inside HabitApp.
  • While you have a balance, the nominated apps open normally and the balance draws down as you use them. At zero, opening one shows the shield.
  • There is no re-shielding cleverness, no per-app budget and no schedule. You have minutes or you do not.

How to use it

  • Nominate only the apps you actually lose time to. Everything else on the phone stays untouched.
  • Grant the Screen Time permission when asked — without it the locking half of the app cannot function.

Limits

Apple's Screen Time picker only ever lists apps on the device it is running on, and the tokens it returns cannot be read, exported or synced to another phone.

The Nope button

In the app

A single button that pays you for closing an app you were about to open.

How it works

  • The button floats over the main view. You press it at the moment you catch yourself reaching for the feed.
  • It pays first and asks afterwards. The credit lands on the press; anything the app wants to know about the moment is asked after you have already been paid, and answering is optional.
  • This is the mechanism with the best evidence behind it: adding a short pause before an app opens cut openings by 57% in a randomised trial, and about a third of the time people closed the app instead of waiting.

How to use it

  • Press it when you notice the reach, not after you have already scrolled. The value is in the interruption.
Family

Family link

In the app

A parent and a child each on their own iPhone, connected through the parent's iCloud account.

How it works

  • The parent creates the link and shares it; the child accepts on their own device. It runs on Apple's CloudKit sharing, so the data belongs to the family's iCloud, not to a server of ours.
  • Each person keeps their own goals, their own balance and their own rewards. The link adds a shared surface between them; it does not merge the two accounts.

How to use it

  • Set the child up on their own device first, then send the link from the parent's phone.

Limits

Both people need their own iPhone and their own Apple account. There is no single-device mode where a child uses a profile on the parent's phone.

The task board

In the app

A parent posts a task with a reward attached; the child accepts it, does it, and submits it for approval.

How it works

  • The parent posts a task with a title, a screen-time reward, an optional dollar amount and an optional expiry.
  • The child sees it as an offer and either accepts or declines. Declining is a real answer and ends the task.
  • When the child marks it done, it goes to the parent for review. Approval is the only status that pays — nothing mints on the child's say-so alone.
  • On approval the screen-time reward mints into the child's own balance, and any dollar amount is added to a running tally the parent is reminded to settle.
  • Each step notifies the other person: a new offer reaches the child, an acceptance and a submission reach the parent.

How to use it

  • Write tasks the way you would say them out loud. "Dishes, tonight" beats a formal description.
  • Set an expiry on anything time-sensitive so a stale offer does not sit on the board.

Limits

No money moves through HabitApp. The dollar side is a figure and a reminder; how it actually gets paid is the family's business.

Parent-managed app limits

In the app

A parent can take ownership of which apps are locked on the child's phone, so the child can no longer edit the list.

How it works

  • It runs on Apple's child-authorization model. The guardian enters their own Apple credentials on the child's device, which is what gives the app the authority to manage that device.
  • The locked-app list is chosen on the child's device with the parent present, because Apple gives no third party any cross-device way to pick apps: the picker only ever lists the device it runs on, and the tokens it hands back are opaque and meaningless on another phone.
  • Once managed mode is on, the child's own controls for editing that list are hidden. Everything downstream — the shield, the drawdown, the balance — behaves exactly as before, just under a list the child cannot change.
  • What the parent can control remotely is deliberately small, because it is the only thing that can honestly sync: a master switch for whether enforcement is on, and a count of how many apps are on the list.

How to use it

  • Do the setup sitting next to your child, on their phone, with your own Apple password to hand.
  • Expect to agree the list together. The device model makes this a conversation rather than something imposed remotely.

Limits

The parent's screen shows how many apps are restricted, not which ones — the app names never leave the child's device in a form anything else can read.

Device activity view

Not built yet

A parent-facing view of which services the child's phone is reaching, and when.

How it works

  • It would run as an on-device network filter on the child's phone, reporting the domains that phone connects to.
  • That is domain-level information, so it can say a phone was talking to TikTok's servers at eleven at night. It cannot say how many minutes were spent in the app, and it degrades as encrypted connection metadata rolls out across the web.

Limits

NOT BUILT. The code exists in the repository but is not part of the shipping app, has never run on a device, and no date is attached to it. Nothing else in the family features depends on it.

Over time

Calibration

In the app

Every couple of weeks the app reads your own record and proposes changes to your goals based on what it finds.

How it works

  • It runs on a rhythm — roughly every other week — and sooner when the record has something urgent to say, like a goal collapsing or a savings goal funding.
  • It reads first and asks second: per-goal kept rates, funded savings goals, slots sitting idle. The questions it asks are generated from what your record actually shows, so week six asks about week six rather than repeating a fixed questionnaire.
  • It can write changes back, but only the ones you selected on the proposal screen. Anything destructive — pausing a goal, retiring a savings goal — takes a second confirming tap.

How to use it

  • Take the calibration when it offers itself. Declining a proposed change is a normal answer and the record keeps it.

The reasoning behind all of it is written out at length.

Why a pause works, why tracking alone does not, why there are no streaks, and what the evidence actually supports — with the sources named.

Read the writing