Habits

A habit is a practice you want to sustain over time. Unlike a task (which is completed and disappears) or an event (which has a specific date), a habit is logged day by day and what matters is consistency, the streak, and the trend.

You tell the agent "I want to create a habit to read every day" and it's created with the frequency you define.

Create a habit

The Administration and productivity agent has the create_habit tool. Define:

• Title — what you want to do ("Meditate", "Run", "Learn English")
• Emoji — visual icon for the dashboard
• Description — free text, optional
• Activity type — classification (exercise, meditation, reading, language, etc.) — affects color and aggregated stats
• Frequency (frequency_type) — three modes: daily, weekly or custom
• Target days (target_days) — which days of the week count, as numbers from 0 to 6 (0 = Sunday, 1 = Monday, …, 6 = Saturday). All seven by default. target_days=[1, 3, 5] is Monday, Wednesday and Friday
• Times per period (target_times_per_period) — how many times it has to be completed in each period. 1 by default
• Reminder — an optional daily push, with a time (08:00)

The frequency + times per period pair is what gives meaning to everything, and it's the part most often misunderstood. "Weekly" on its own doesn't mean once a week: it means N times a week, and that N comes from target_times_per_period.

Frequency	Times per period	Means
daily	1	Once a day
weekly	3	Three times a week
custom	N	N times within the target days

So "I want to go to the gym 3 times a week" is frequency_type="weekly" with target_times_per_period=3 — not a daily habit you're going to miss four days out of seven.

You can also create and configure habits from the Habits tab in the UI.

Log completion

The agent has log_habit to mark a habit as completed on a specific day. From the UI you have two paths:

• Quick — tap the card checkbox on the dashboard and it's logged for today
• Detailed — open the log dialog and add duration (with hours/minutes selector) and optional notes. Useful if you want to know not just whether you meditated, but for how long

Duration is a property of the log, not of the habit. You don't define "45 minutes expected" when you create it; you write down the minutes you put in when you log the session ("I did 45 minutes of exercise"). The habit answers whether you did it; the log answers how much.

You can also log past days by tapping the corresponding cell on the contribution grid.

The contribution grid

The habit detail screen shows a GitHub-style grid where each cell is a day. The state is binary — you did the habit or you didn't:

• Green — you completed that day
• Neutral — you didn't complete it (or the day hasn't come yet)

You can change the scale between week, month, quarter and year to see the trend at different resolutions.

In the chat, the grid returned by read_habit_calendar also tells apart the days that weren't yours to do: ■ is a completed day, □ a target day you missed, and · a day that wasn't even scheduled. Missing a day that wasn't yours doesn't count as missing.

Streaks and stats

The read_habit_stats tool (and the detail UI) shows:

• Current streak — how many consecutive days you've completed
• Best streak — historical record
• Completion rate — percentage of target days completed in the last 30 days by default. The window is configurable: you can ask the agent "how am I doing with the gym over the last 90 days?" and it adjusts it
• Total completions — every time you've completed the habit

read_habit_calendar returns a text representation of the grid — useful when you ask the chat "how's my meditation habit?". Its window is configurable too: 90 days by default, up to a maximum of one year.

Pause and archive

If you need to pause a habit temporarily — vacation, illness, whatever — edit_habit puts it in paused state. Stats aren't deleted and the accumulated streak isn't broken. When you reactivate it (status=active), it resumes where it was without breaking the history.

The archived state takes it out of the dashboard without deleting it, in case you want to review the history later.

delete_habit is soft-delete: it marks a deleted_at but keeps the row in case you need to recover it.

Tools summary

Tool	What for
read_habits	Lists active/paused/archived habits with their current streak.
create_habit	Creates a new habit with frequency, target days, times per period and type.
edit_habit	Rename, change frequency or state (preserves streaks when pausing).
delete_habit	Soft-delete.
log_habit	Marks completion for a day, with optional duration and notes (requires a valid habit_id).
read_habit_stats	Current + best streak + completion rate (30 days by default).
read_habit_calendar	Contribution grid in text (90 days by default, one year maximum).