# Habits

URL: https://docs.clatri.com/en/space/habits/

> How habits work in Clatri: create them with a frequency and target days, log completions, read the contribution grid, streaks and completion rate.

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). |