--- title: Habits --- # Habits ## What it is > **In-development, off by default** (gated by the `habits` unreleased feature / `habitsEnabled` > setting; reveal via Settings → Features, or `AMC_SHOW_HABITS=1`). A first-party personal > habit / daily-routine tracker that lives in the **Productivity** sidebar group as the sibling of > Coffer (the finance tracker). Fully local — no cloud, no AI, no cost. A native full-pane panel for tracking daily habits — exercise, water, sleep, meditation, or anything you define. You create habits, tap to log them each day, and watch streaks and completion build. It was requested by a user who wanted personal-life tracking (habits + expenses) inside Omniscio; Coffer covers expenses, this covers habits. When enabled, it appears as a **Habit Tracker** row in the Productivity group of the projects sidebar (a calendar-check icon). Clicking it opens a full-width panel (it hosts no Claude session — it's a native tool surface, `panelOwnsLayout`). It works on the phone web client too (`mobile: ready`). ## Where to find it Habits lives in the **Productivity** sidebar group, beside Coffer, the finance tracker. It is in development and off by default, so it stays hidden until you reveal it under Settings → Features. ## How it behaves ### The four views (top tabs: Today · Habits · Calendar · Trends) - **Today** — your day as a tappable checklist. Each habit is a row with a category icon, its name, a target/cadence label, a streak flame + count, and a log control that depends on the habit's kind: - *Yes/no (binary)* and *Duration* → a **check** button (tap = done; duration logs its target so a one-tap "did my 30 minutes" counts as complete). - *Count* → a **− / +** stepper (log toward a goal, e.g. 8 glasses of water). - *Scale* → a **1–5** picker (e.g. mood or energy). A day-completion **ring** (done ÷ due-today) sits at the top. On first run with no habits, the view shows a friendly empty state with an "add your first habit" prompt plus one-tap starters (Exercise, Water, Sleep). - **Habits** — manage your habits, grouped by category, with edit and delete (delete asks to confirm). A **New habit** button opens the editor modal: name, category, kind (yes-no / count / duration / scale), target + unit, cadence (specific weekdays **or** a "times per week" goal — one or the other, not both), and an optional reminder time. - **Calendar** — pick a habit to see a GitHub-style **contribution grid** (16 weeks) colored by completion, plus stat cards: current streak, longest streak, and completion %. - **Trends** — completion-by-category bars (last 30 days) and a daily completion **sparkline** (last 14 days), computed from your real logged entries. ### Daily reminders Give a habit a reminder time and, when the feature is on, a background scanner drops **one passive inbox nudge per habit per day** ("Time to log ") once its time arrives and it isn't yet completed — with a one-click **Open Habit Tracker** action. It reuses the same nudge engine as the AI-coaching daily check-in, fires at most once per habit per day (a stable per-habit-per-day dedup key), and never force-foregrounds the app. Turn all nudges off with the `habitsRemindersEnabled` setting (on by default when the feature is enabled). ### How streaks & completion work Nothing is precomputed or cached — streaks and completion % are **derived on read** from your logged entries against the habit's *current* target, so changing a target never leaves a stale flag. A "day" is always your local calendar date; the math is DST-safe. A habit is "due" on its scheduled weekdays (or every day if unscheduled); a "times per week" habit's completion is scaled to its weekly goal so rest days don't count against it. Today's not-yet-done habit never breaks a streak until the day ends. ## For agents ### Data model (local SQLite) Two additive tables: - `habit_definitions` — one row per habit (name, icon, category, kind, target, cadence, reminder time, sort order; soft-deletable). - `habit_entries` — one row per habit per day, `PRIMARY KEY (habit_id, date)`, so logging is an idempotent upsert. There is deliberately **no** stored "completed" column — completion is derived. Deleting a habit soft-deletes its definition; its entries are hidden (reads join the active definition). Nothing leaves your machine. ### For agents — where the code lives - Backend: `src/main/db/queries-habits.ts`, stat math in `src/main/services/habits/` (`habit-stats.ts`, `habit-dates.ts`, `habits-service.ts`), reminders in `habit-reminder-scanner.ts` + `habit-reminder-gate.ts`. - IPC: channels in `src/shared/ipc-channels/habits.ts`, Zod schemas in `src/shared/ipc-schemas/habits.ts`, handlers in `src/main/ipc/habits-handlers.ts` (`HABITS_LIST` / `_CREATE` / `_UPDATE` / `_DELETE` / `_REORDER` / `_LOG` + read channels for today/stats/calendar/category/daily). - Renderer: `src/renderer/src/features/habits/` (panel + four views + editor modal). Gating: the `habits` entry in `src/shared/unreleased-features.ts`, the manifest in `src/shared/integrations/habits.ts`, the `UNRELEASED_PROJECT_GATES` gate in project-visibility, and the ui-registry entry. - Types: `src/shared/types/habits.ts`. ## Related Coffer, the finance tracker in the same sidebar group, is its closest sibling; both keep their data on your machine.