- TypeScript 56%
- Kotlin 40.8%
- Shell 1%
- CSS 0.8%
- JavaScript 0.7%
- Other 0.6%
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> |
||
|---|---|---|
| .claude | ||
| docs/screenshots | ||
| packages | ||
| .dockerignore | ||
| .env.example | ||
| .eslintrc.json | ||
| .gitignore | ||
| CLAUDE.md | ||
| docker-compose.yml | ||
| Dockerfile | ||
| flake.nix | ||
| giantdot.jpg | ||
| habit details page inspo.jpg | ||
| newidea for header.jpg | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| stats page inspo.jpg | ||
| tsconfig.base.json | ||
| vitest.config.ts | ||
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
- Features
- Clients
- Getting started
- Deployment
- Project layout
- Architecture
- API reference
- Testing
- Integrations
- Licence
Screenshots
The web client, dark theme.
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. --debugcannot upgrade a release install, and vice versa — the signatures differ, and the install fails withINSTALL_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.



