A Self hosted habit tracking application written for web and android.
  • TypeScript 56%
  • Kotlin 40.8%
  • Shell 1%
  • CSS 0.8%
  • JavaScript 0.7%
  • Other 0.6%
Find a file
Matthew Weber 00a1a50713 Redesign Android Compose screens and web habits page
Adds ScreenHeader, FormPieces and SheetFrame components and moves the
screens onto them; updates HabitsPage.tsx to match.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-11 17:12:34 -05:00
.claude redesign 2026-09-05 15:56:20 -04:00
docs/screenshots Show the app in the README 2026-08-09 13:08:41 -04:00
packages Redesign Android Compose screens and web habits page 2026-11-11 17:12:34 -05:00
.dockerignore first commit 2026-08-02 19:08:22 -04:00
.env.example Fix what a review turned up 2026-08-18 15:13:27 -04:00
.eslintrc.json Delete the abandoned Expo app 2026-08-18 15:26:22 -04:00
.gitignore Stop ignoring the Kotlin app's data package 2026-08-05 17:28:36 -04:00
CLAUDE.md Update CLAUDE.md for the UI redesign 2026-11-11 17:12:34 -05:00
docker-compose.yml Fix correctness and security defects, wire up dead subsystems, redesign Today 2026-08-05 13:25:35 -04:00
Dockerfile Fix correctness and security defects, wire up dead subsystems, redesign Today 2026-08-05 13:25:35 -04:00
flake.nix first commit 2026-08-02 19:08:22 -04:00
giantdot.jpg Hide the pull-to-refresh indicator until it is pulled 2026-08-05 17:05:59 -04:00
habit details page inspo.jpg new habits page and stats 2026-08-06 03:27:30 -04:00
newidea for header.jpg Rework the Today header and remove the doubled top inset 2026-08-05 17:13:28 -04:00
package-lock.json redesign 2026-09-05 15:56:20 -04:00
package.json Delete the abandoned Expo app 2026-08-18 15:26:22 -04:00
README.md Bring the docs back in step with the app 2026-08-25 01:18:52 -04:00
stats page inspo.jpg new habits page and stats 2026-08-06 03:27:30 -04:00
tsconfig.base.json first commit 2026-08-02 19:08:22 -04:00
vitest.config.ts Make the keyboard shortcuts work as advertised 2026-08-25 01:18:45 -04:00

Habits

A self-hosted habit tracker with a web app, a native Android client, and a journal that records what you did and how much of it.

Habits are more than a checkbox here: a habit can be a count (eight glasses of water), a duration you time in the app (an hour of reading), or a quota you meet however you like across a week or a month (the gym, three times). Ticking one off offers you a note, and a note can carry figures — 2,350 calories against a target of 2,000 — which the journal draws as bars.


Contents


Screenshots

The web client, dark theme.

Today Journal
Today — the day's habits, a count part-filled, a quota met Journal — notes with their trackers drawn as bars
Stats Habits
Stats — health, streak, consistency trend, per-habit rates Habits — grouped by category, with the week so far

Features

Habits and schedules

A habit has a name, a colour, an icon, an optional category, and a schedule. Icons are emoji, picked from a searchable set of about 250 across nine groups — type "run" for the one, "health" for the lot. Habits made before emoji keep the stroke icon they had; both are read, so nothing needed rewriting.

Schedules come in two kinds, and the difference runs deeper than it looks.

Day-based schedules name which days:

Schedule Meaning
daily Every day
weekdays Monday to Friday
weekends Saturday and Sunday
specific_days Whichever days you pick

Periodic schedules name how many days, and leave the choice to you:

Schedule Meaning
times_per_week N days in a Monday–Sunday week
times_per_month N days in a calendar month

A periodic habit can never miss a day — "three times a week" says nothing about Tuesday — so no day is ever marked as a failure, and its streak counts weeks or months rather than days. Only a period that ends short falls short, and a period still running never counts against you.

targetCount composes with either kind: eight glasses of water three times a week means three days on which you drank eight.

Timed habits and timers

Set a habit as timed and its target becomes a duration. Under the hood it is the same field counting seconds, so streaks, history and the note prompt all work unchanged — the flag only changes how the number is read and shown.

Timers are held server-side, storing only the instant a session began. A session survives closing the app and appears on whichever client you pick up next. Stopping banks the time against the day the timer started, so a session running past midnight counts towards the evening it belongs to.

A timed habit can always be marked done by hand, and doing so asks how long it took — pre-filled with whatever is still owed, so "yes, all of it" is one tap. The app has no idea how long a session away from the timer ran, and the number is the whole point of a timed habit, so it is not one it should invent. On the home-screen widget, where there is nowhere to ask, tapping a timed habit opens the app instead.

Changing the duration does not rewrite your history. An hour a day that becomes ten minutes a day applies from today onwards: the half-hours that missed the hour stay missed, and going the other way, days you finished under the old target stay finished. Each entry remembers what it was asked for, so the calendar, the streak and the percentages all keep telling the same story about a day after you change your mind about the next one.

Streaks and statistics

Streaks are computed from your completion history, and corrected on read: a streak that lapsed because a day simply went by is reported as broken even though nothing was written to the database to say so.

The stats screens cover a rolling week, month, year, or all time, with:

  • Habit health — the share of finished, scheduled days you met. Today is excluded until it is either met or over, so the figure never sags each morning and can read 100% before bedtime.
  • Consistency trend — daily points up to about two months, monthly beyond.
  • Per-habit breakdown — done, target, missed, rate and streaks, sorted by streak, rate, name or most-missed. Your own ordering of the habit list answers a different question than "which of these is going well".

Days before a habit existed are never counted as misses. A completion back-filled onto such a day still counts, because the entry is evidence you did it.

The journal

Completing a habit offers a note, and finishing everything scheduled offers a note about the day. Both are markdown, both are optional, and the prompt is always skippable.

A habit can also opt out of being asked. Some habits are just a box, and being asked whether you have anything to say about flossing every night is how you learn to dismiss the prompt without reading it — which then happens on the evenings that did have something.

  • Day notes — one per day, about the day as a whole.
  • Habit notes — attached to a specific completion.
  • Images — paste, drop, or pick; stored beside the database.
  • Export — the whole journal as one markdown file, grouped by day.

Deleting a habit note clears the note only. The completion stays, and so does the streak that depends on it.

Trackers

A note can carry numbers as well as words: a label, a value, an optional target, and a unit you type yourself. There is no list of known units, because any list is missing the one you want.

The target's presence decides the display. With one, the journal draws a bar scaled to max(value, target) with a marker where the target sits — so going over pushes the fill past the marker rather than pinning a capped bar under a "118%" label. Without one, it is simply the figure.

Nothing is coloured as good or bad: 2,350 calories against 2,000 and 420 pages against 400 are opposite outcomes, and a tracker cannot tell which it is looking at.

Trackers you have used before are offered as one-tap chips on the next note, carrying the label, unit and target — but never the value.

Goals, categories and reminders

  • Goals — a target number of completions for a habit over a date range, with progress and an on-track indicator. A "completion" is a day that met the habit's target, the same thing the streak and the statistics count — so "read thirty times" means thirty days of reading, not thirty half-hours or thirty glasses.
  • Categories — colour and icon, used to group and filter habits.
  • Reminders — a per-habit time, checked once a minute against the wall clock in your timezone. Only fires for habits scheduled today and not yet done; a periodic habit stops reminding once its quota is filled.

Clients

Client Path Status
Web packages/web React 18 + Vite, served by the server in production
Android packages/android Kotlin + Jetpack Compose, with home-screen widgets

The Android app ships three Glance widgets — a checklist, a progress ring and a streak counter — which draw from a local cache and refresh in the background, so they render immediately even when the server is slow or unreachable.

Keyboard shortcuts

The web client is navigable from the keyboard. Press ? for the list.

Key Goes to
d Today
h Habits
j Journal
g Goals
s Stats
, Settings

n opens a new habit, t switches light and dark, ? shows the list. Every one is rebindable in Settings — click a shortcut, press the key you want, Escape to cancel. Modifier chords like Ctrl+K work if you prefer them, and shortcuts are ignored entirely while you are typing in a field.


Getting started

Requirements

  • Node 20+ (this repo is developed against 22)
  • Docker for deployment
  • Android Studio or Gradle 8 + JDK 17 for the Android client

On NixOS, wrap Node commands so they find a toolchain:

nix-shell -p nodejs_22 --run "npm install"

Development

npm install
cp .env.example .env          # then edit the secrets
npm run dev                   # server on :3001, web on :5173

The web dev server proxies /api and /socket.io through to the server, so open http://localhost:5173 and everything works from one origin.

Other useful scripts:

Command What it does
npm run dev:server Server only
npm run dev:web Web only
npm run build shared → server → web, in that order
npm run typecheck Server and web
npm run lint ESLint across every package
npm test Vitest, once
npm run test:watch Vitest, watching
npm run db:generate Generate migration SQL from the schema
npm run db:migrate Apply migrations
npm run db:studio Drizzle Studio

@habits/shared is a compiled package whose main points at dist/, so it must be built before the server or web can typecheck. predev, build, typecheck and test all do this for you; run npm run build -w @habits/shared by hand if you invoke tsc directly.

Environment

Variable Required Default Notes
PORT no 3001
DATABASE_PATH no ./data/habits.db Note images are stored beside it
NODE_ENV no development
JWT_SECRET in production — openssl rand -base64 48
JWT_REFRESH_SECRET in production — Must differ from the above
UPLOADS_PATH no beside the database Where note images are written
DISABLE_REMINDERS no false true stops reminder pushes

Note images default to a directory next to DATABASE_PATH, so whichever volume keeps the database keeps the images too. Set UPLOADS_PATH only if you want them somewhere else — and make sure that somewhere is on a volume as well, or they will not survive the container being replaced.

In development the JWT secrets fall back to a known insecure value and warn. In production the server refuses to start without them.


Deployment

Docker

docker compose up --build -d

Compose refuses to start without the two JWT secrets, so put them in a .env file beside docker-compose.yml. The database and note images live on the habits_data volume, and the container healthchecks GET /api/health.

In production the server also serves the built web app as static files, so one container is the whole thing.

Building the Android APK

cd packages/android
./build-apk.sh                  # signed release APK in dist/, installed on a
                                # connected device if there is exactly one
./build-apk.sh --no-install     # build it and stop
./build-apk.sh --debug          # debug build instead
./build-apk.sh --init-keystore  # create the signing key, once, interactively

Two things worth knowing:

  • The signing key can never change. Android refuses to update an app whose signature moved, so replacing the keystore means uninstalling and losing the local data on the device. Back up habits-release.keystore.
  • --debug cannot upgrade a release install, and vice versa — the signatures differ, and the install fails with INSTALL_FAILED_UPDATE_INCOMPATIBLE. Use the variant already on the device.

versionCode is the git commit count and versionName carries the short SHA, so every build outranks the last and a tester can say exactly which one they are running.


Project layout

packages/
├── shared/      Types, date-key helpers, schedule rules, constants
├── server/      Express + SQLite (Drizzle), REST API, Socket.IO, reminders
├── web/         React 18, Vite, Tailwind, shadcn/ui, TanStack Query
└── android/     Kotlin, Jetpack Compose, Retrofit, DataStore, Glance widgets

shared is the contract. Anything both a client and the server must agree on — what a date key means, whether a day counts towards a habit's record, how a period is bounded — lives there and is mirrored in Kotlin under packages/android/.../util/.


Architecture

Date keys

A date key is a YYYY-MM-DD string naming one calendar day in the owning user's configured timezone. Completions are stored as <dateKey>T12:00:00.000Z and looked up by prefix.

Every date key, on the server and in every client, must come from the helpers in shared/src/utils/date.ts with the user's timezone passed in. Deriving one from UTC or from the browser's local zone silently reads and writes the wrong day for anyone whose offset crosses midnight — including, subtly, a habit's own creation day, which is a UTC instant and must be converted rather than sliced.

Database and migrations

SQLite via better-sqlite3 and Drizzle, in WAL mode with foreign keys on. Migrations are plain SQL under packages/server/src/db/migrations/, applied by a single runner shared by server startup and npm run db:migrate, each inside a transaction and tracked in __migrations.

Tables: users, refresh_tokens, categories, habits, habit_completions, goals, push_tokens, daily_notes, note_images, habit_timers.

Authentication

JWT access tokens lasting 15 minutes, plus refresh tokens stored in the database and valid for 30 days. Refresh tokens are single-use and rotate, so a client must persist the new one it receives and must serialise concurrent refreshes — two requests spending the same token will sign the user out. Both first-party clients do this; anything new should too.


API reference

All routes are under /api and require Authorization: Bearer <token> except where noted.

Group Endpoints
Auth POST /auth/register, /auth/login, /auth/refresh, /auth/logout — no token needed
Habits GET /habits, GET /habits/:id, POST /habits, PUT /habits/:id, DELETE /habits/:id
Completion POST /habits/:id/complete, POST /habits/:id/uncomplete
Timers POST /habits/:id/timer/start, POST /habits/:id/timer/stop, DELETE /habits/:id/timer
Categories GET, POST /categories, PUT, DELETE /categories/:id
Goals GET, POST /goals, PUT, DELETE /goals/:id
Stats GET /stats/overview, /stats/habit/:id (both take ?period=week|month|year|all), /stats/heatmap
Notes GET /notes/feed, GET/PUT/DELETE /notes/daily/:date, PATCH/DELETE /notes/completions/:id
Trackers GET /notes/trackers/recent
Images POST /notes/images (raw bytes), GET/DELETE /notes/images/:id
Export GET /notes/export — the journal as markdown
Push POST /push/register, DELETE /push/unregister
Settings GET, PUT /settings
Integrations GET /integrations/checkbox/status, POST /integrations/checkbox/sync — 501 stubs, see Integrations
Health GET /api/health — no token needed

Unknown /api/* paths return a JSON 404 rather than falling through to the single-page app.


Testing

npm test

Coverage is deliberately weighted towards the things that were silently wrong before, rather than spread evenly:

Suite Covers
shared/src/utils/date.test.ts Date keys across timezones, DST, boundaries, period arithmetic
shared/src/utils/duration.test.ts Duration formatting and parsing
server/src/services/streaks.test.ts The streak algorithm, day-based and periodic, DB-free
server/src/services/stats.test.ts Rates, missed days, trend bucketing
server/src/db/migrator.test.ts Migration idempotency and recovery
server/src/routes/routes.test.ts Auth, tenant isolation, validation
server/src/routes/notes.test.ts Notes, images, trackers, export
web/src/lib/keybindings.test.ts Chord spelling, rebinding, conflicts

Test files are excluded from build output but are still typechecked.


Integrations

A Habits widget for the homepage dashboard lists the habits scheduled today and lets you tick them off without leaving the dashboard. It talks to this API through the homepage's own server.

externalCheckboxHabitId and the routes under /api/integrations are placeholders for a future Checkbox sync and currently return 501.


Licence

None yet.