"You must do one more thing, and you'll get to rest."
Steal your time back.
Momo is a task management app built for people who struggle with avoidance, procrastination, and the overwhelming weight of everyday tasks. Not a power-user productivity suite — a quiet, daily companion that asks only one thing of you: one small step, today.
🌐 Live version: momotask.app
📖 Documentation: jp1337.github.io/momo
📸 Screenshots
✨ The Name
The name Momo comes from Michael Ende's 1973 novel Momo — one of the most quietly radical books about time, attention, and what it means to be present.
In the story, the Grey Gentlemen — shadowy figures carrying briefcases — visit ordinary people and convince them to "save time." They tell people to stop lingering, to cut out the things that don't produce anything: long conversations, idle afternoons, play, rest. People comply. They become efficient. They become joyless. They lose themselves.
Momo is a small, homeless girl who has a rare gift: she truly listens. And through that gift, she sees what others cannot — that the Grey Gentlemen are stealing people's time, not saving it. She fights them. Alone. Slowly. One step at a time.
The parallel to procrastination and avoidance is not accidental.
When anxiety or overwhelm turns every task into a wall, when the Grey Gentlemen of your own mind tell you that you're behind, that you'll never catch up, that you should just wait until tomorrow — Momo is on your side. She doesn't ask you to be productive. She asks you to do one thing. Just one. That's enough for today.
This app is named in her honor.
🌟 Features
- Onboarding Wizard — Guided 4-step setup for new users: learn the core concepts (Quest, Energy, Coins, Streaks), create a first topic, add tasks, and enable notifications. Every step is skippable; existing accounts are unaffected.
- Daily Quest — One small task, chosen for you each day. No overwhelm, just one step forward.
- Energy-aware Daily Quest — Permanent check-in card on the dashboard: tell Momo whether you're at high / medium / low energy, and it auto-swaps the daily quest for a better-matching task (with Undo). Topics can set a default energy level that new tasks inherit. Quick Wins and 5-Minute Mode sort by energy fit. 14-day energy trend on
/stats. Every check-in is logged so re-check-ins (morning HIGH, afternoon LOW) are preserved for pattern analysis.
- Topics & Subtasks — Break big projects (like "Moving" or "Tax Return") into tiny, manageable pieces. Drag & drop to reorder tasks within a topic.
- Sequential Topics — Flip a toggle on any topic to turn it into an ordered chain: only the first still-open task is eligible for the daily quest, and the drag & drop order decides what comes next. Perfect for projects where "buy the boxes" has to happen before "pack the boxes". Snoozing a task advances the chain so one paused step doesn't freeze the whole topic.
- Topic Templates — One-click import for curated starter topics. Pick from Moving (10 sequential tasks), Tax Return (6 sequential tasks), Workout Routine (7 parallel tasks) or Household (6 recurring chores — laundry, vacuuming, kitchen, bathroom, windows, bedding — with sensible default intervals) and Momo creates a fully populated topic with icons, colours, default energy level and sensible priorities. Template titles are resolved in your current UI language at import time and become normal, editable tasks. Extend the catalogue by adding an entry to
lib/templates.ts.
- Recurring Tasks — Four schedule types: Interval (every N days, rolling), Weekday (e.g. every Mon + Wed), Monthly (same day each month), Yearly (same date each year). Each type has a Fixed/Rolling toggle: fixed = always advance from the scheduled date (calendar-aligned); rolling = advance from the completion date. iCal export generates correct
RRULE per type. Habit streaks count in the natural period for the type (days / weeks / months / years).
- Habit Tracker — A GitHub-style year heatmap per recurring task on
/habits. Every completion lights up the day it happened; stat pills show totals for this year, 30 days, and 7 days. An amber flame pill tracks each habit's — consecutive periods you hit the habit, in the unit that fits the recurrence (days, weeks, months). Your all-time best streak is shown underneath, with a "New best" flourish when you beat it. Browse past years with the year selector. Uses your real completion events — no fake "expected" days, no invented streaks.
🔐 Authentication
Sign in with the account you already have. No new password to forget.
| Provider | Live (momotask.app) | Self-hosted |
|---|
| GitHub | ✅ | ✅ (own OAuth App) |
| Discord | ✅ | ✅ (own OAuth App) |
| Google | ✅ | ✅ (own OAuth App) |
| Microsoft (private accounts only — Outlook/Hotmail/Live/Xbox) | ✅ | ✅ (own Azure App) |
| OIDC (Authentik, Keycloak, …) | — | ✅ |
Optional two-factor authentication — either TOTP (Aegis, 2FAS,
Google Authenticator, Authy, 1Password, …) or Passkeys (Touch ID,
Windows Hello, iCloud Keychain, YubiKey, …). Passkeys additionally enable
passwordless primary login: once registered, you can sign in with just
a fingerprint or PIN — no OAuth round-trip required. Self-hosters can
enforce a second factor for every account by setting REQUIRE_2FA=true.
See Two-Factor Auth Guide for the technical
details and OAuth Setup Guide for provider setup.
Active session management + login alerts — view all active sessions
(browser, OS, IP, timestamps) in Settings and revoke any you don't recognise.
Enable opt-in new-device login notifications to receive an alert on all
your configured channels the moment an unfamiliar device signs in to your
account.
🛠️ Tech Stack
| Layer | Technology |
|---|
| Frontend | Next.js 16 (App Router) + React 19, TypeScript, Tailwind CSS v4 |
| Animations | Motion |
| Auth | Auth.js v5 (GitHub, Discord, Google, Microsoft (private accounts), OIDC) |
| Database | PostgreSQL 18 + Drizzle ORM |
| i18n | next-intl — German, English, French (cookie-based, no URL prefix) |
| Push Notifications | Web Push API (VAPID, no third-party) |
| API | OpenAPI 3.1.0 + Personal Access Tokens (Bearer) |
| Container | Docker (Node.js 24 LTS) |
| Orchestration | Kubernetes |
| CI/CD | GitHub Actions (native multi-arch: amd64 + arm64) |
| Image Registries | GHCR, Docker Hub, Quay.io |
Note for React developers: Next.js is a React framework. All UI is written in React — Next.js adds routing, server-side rendering, API routes, and PWA support on top.
🎨 Design
Momo is intentionally cozy. Both the dark and light themes use warm, earthy tones — no harsh whites, no cold blues, no sterile greys. The goal is an app you want to open, not one that feels like a spreadsheet.
- Dark theme: Deep forest greens and near-blacks with warm amber accents
- Light theme: Pale sage paper, not cream — a daylight-in-the-woods tone rather than the warm-serif-on-cream look most productivity apps default to
- Typography: Fraunces (once per page, large — the Daily Quest or a page title) · JetBrains Mono (tasks, figures) · Instrument Sans (everything else)
- Animations: Subtle, purposeful — a small celebration when you finish something, not a distraction
🚀 Quick Start (Docker Compose)
Prerequisites
- Docker & Docker Compose
- Node.js 24+ (for local development only)
- A GitHub or Discord OAuth App (see OAuth Setup)
1. Clone the repository
git clone https://github.com/jp1337/momo.git
cd momo
2. Configure environment variables
cp .env.example .env.local
# Edit .env.local with your credentials
See Environment Variables for a full reference.
3. Start with Docker Compose
docker compose up -d
The app is available at http://localhost:3000. Database migrations run automatically before the server starts — no manual step needed.
🧑💻 Local Development (WSL / Linux)
# Install dependencies
npm install
# Start PostgreSQL via Docker Compose
docker compose up db -d
# Run database migrations (local dev only)
npx drizzle-kit migrate
# Start the development server
npm run dev
The app runs at http://localhost:3000.
Running Tests
Integration tests run against a separate momo_test database (dev data is never touched):
docker compose up db -d # database must be running
npm test # creates momo_test, migrates, runs 29 tests
npm run test:watch # re-run on file changes
See docs/testing.md for the full test catalogue and setup details.
📦 Container Images
Momo images are published to three registries on every release for redundancy:
| Registry | Image |
|---|
| GitHub Container Registry | ghcr.io/jp1337/momo |
| Docker Hub | docker.io/jp1337/momo |
| Quay.io | quay.io/jp1337/momo |
Pull from whichever is available:
docker pull ghcr.io/jp1337/momo:latest
# or
docker pull jp1337/momo:latest
# or
docker pull quay.io/jp1337/momo:latest
📖 Documentation
Full documentation is available at jp1337.github.io/momo
| Guide | Description |
|---|
| Deployment | Docker Compose, production checklist, Kubernetes reference |
| Environment Variables | All configuration options |
| OAuth Setup | GitHub, Discord, Google, Microsoft & OIDC configuration |
| API Reference | All REST endpoints — interactive Swagger UI at /api-docs |
| Database | Schema overview, migrations, Drizzle Studio |
| DSGVO / GDPR | Compliance guide for operators |
| SEO | Search-engine setup: metadata, robots, sitemap, JSON-LD |
🏗️ Project Status
| Phase | Status | Description |
|---|
| Phase 1 – Foundation | ✅ Done | Next.js 16 + Auth.js v5 + Drizzle ORM + Design System |
| Phase 2 – Core Tasks | ✅ Done | Task CRUD, Topics, Recurring |
| Phase 3 – Daily Quest | ✅ Done | Quest algorithm, Dashboard |
| Phase 4 – Gamification | ✅ Done | Coins, Streaks, Animations |
| Phase 5 – Wishlist | ✅ Done | Wishlist CRUD, Budget tracking, Affordability, Coin-unlock |
| Phase 6 – PWA & Push | ✅ Done | PWA manifest, Service Worker, VAPID push, Daily quest & streak notifications, Settings page |
| Phase 7 – Deployment | ✅ Done | Multi-stage Docker, GitHub Actions (GHCR + DockerHub + Quay), Security Headers, Rate Limiting, K8s manifests |
| Phase 8 – Polish | ✅ Done | Multilingual (DE/EN/ES/FR/NL/RU/ZH), DSGVO compliance, Dark mode redesign, self-hosted fonts, data export, account deletion |
| Phase 9 – API & Keys | ✅ Done | Public REST API, Personal Access Tokens, Swagger UI, Account Linking, Font Awesome icons, SVG Logo |
| Phase 10 – Statistics & Admin | ✅ Done | Personal stats page, Admin panel, Mobile bottom navigation |
| Phase 11 – UX & Anti-Procrastination | ✅ Done | Procrastination counter, postpone limit, bonus coins, task breakdown, time estimates, Quick Wins, public landing page, dashboard redesign, FA icon picker |
| Phase 11 – Bugfixes (2026-04-05) | ✅ Done | Timezone-aware daily quest selection, immutable statistics counter, task breakdown stat increment, mobile task form z-index fix |
| Lichtkegel Phase 2 (2026-08-28) | ✅ Done | Zahlen-Seiten: /stats als Progress-Tab, Wunschliste als Zeilen, Errungenschaften als Liste; Messeinheit sind jetzt Zustände statt Routen (10 statt 6) |
🚢 Production Checklist
Before deploying Momo to production, verify all items below:
See the full Deployment Guide for AUTH_SECRET rotation procedures and Kubernetes deployment steps.
🤝 Contributing
Momo is open source — every contribution is welcome, from a one-line typo fix to a full feature.
Good First Issues
Looking for a place to start? These areas are well-scoped and don't require deep knowledge of the whole codebase:
| Area | What to do |
|---|
| Translations | Add missing keys or improve phrasing in messages/*.json. Run npm run check:i18n to find gaps. |
| Tests | Add unit tests in __tests__/ for an uncovered lib/ function. Run npm test to verify. |
| Docs | Improve or expand pages in docs-site/ (user-facing) or docs/ (operator-facing). |
| Accessibility | Audit components for missing aria-label, keyboard navigation, or colour-contrast issues. |
| New template | Add a new topic template in lib/templates.ts + translation strings in messages/*.json. |
Browse open issues — issues tagged good first issue are specifically chosen for newcomers.
Development Setup
# 1 — Clone and install
git clone https://github.com/jp1337/momo.git
cd momo
npm install
# 2 — Start the database
docker compose up db -d
# 3 — Copy and fill in environment variables
cp .env.example .env.local
# 4 — Run migrations
npx drizzle-kit migrate
# 5 — Start the dev server
npm run dev
The app is then available at http://localhost:3000.
Before opening a PR
npm test # all 1 680+ integration tests must pass
npm run check:i18n # no missing translation keys
npx eslint . # no lint errors
npx tsc --noEmit # no TypeScript errors
Commit convention
Momo uses Conventional Commits:
feat(scope): description / fix(scope): description / test(scope): ...
Scopes: auth, tasks, topics, daily-quest, gamification, wishlist, push, ui, db, api, docs.
📜 License
MIT — see LICENSE for details.
Named after Momo, by Michael Ende. For everyone whose Grey Gentlemen have been stealing their time.
