> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Aritmética de calendário (@date)

> @date calcula o que modelos contam mal: dias entre duas datas, uma data mais um deslocamento, o dia da semana e expressões como 'sábado passado' ou 'há 3 semanas'. Pura, offline e somente leitura.

Modelos de linguagem leem datas bem e contam mal: quantos dias entre 14 de março e 17 de abril, que dia foi o sábado passado, quanto é três semanas antes do dia 5. O `@date` responde isso pelo calendário, não de cabeça. Todo verbo é **puro, offline e somente leitura**: nenhum arquivo, rede ou credencial é tocado, e a ferramenta roda em paralelo com outras.

Ele conta a partir da **data atual**, que o [`CHATCLI_NOW`](/pt/reference/environment-variables) fixa para uma execução inteira, então uma conversa reproduzida do passado lê "sábado passado" contra o dia certo.

```text theme={"system"}
<tool_call name="@date" args='{"cmd":"diff","args":{"from":"2023-03-14","to":"2023-04-17"}}' />
<tool_call name="@date" args='{"cmd":"resolve","args":{"expr":"last saturday"}}' />
<tool_call name="@date" args='{"cmd":"add","args":{"date":"2023-01-31","months":1}}' />
```

| Verbo | Argumentos | O que faz |
| - | - | - |
| `now` | | a data atual, o dia da semana e a hora |
| `diff` | `from`, `to?` (padrão hoje) | dias de calendário, semanas e dias, meses de calendário e dias, e o tempo decorrido; diz também quantos dias dá **contando as duas pontas**, então uma leitura inclusiva nunca é chute |
| `add` | `date?` (padrão hoje), `days?`, `weeks?`, `months?`, `years?` | a data que fica a essa distância (negativo = antes); fim de mês é ajustado para o último dia de um mês mais curto, então 31 de janeiro mais um mês é 28 de fevereiro |
| `weekday` | `date?` | o dia da semana de uma data |
| `resolve` | `expr`, `as_of?` | `yesterday`, `tomorrow`, `last` ou `next` mais um dia da semana, `N days\|weeks\|months\|years ago`, `in N days\|weeks\|months`, como data concreta |

As datas são lidas como `2023-03-14`, `2023/03/14`, `2023-03-14 18:11`, RFC 3339 ou a forma que o [`@session`](/pt/context/session-search) imprime (`2023-03-14 (Tue) 18:11`); `today` e `now` valem a data atual.

## O que as respostas dizem

O `diff` informa dias de calendário (a data posterior menos a anterior, ignorando a hora), então uma sessão salva dia 15 às 18:11 e uma pergunta dia 18 à 01:48 estão a **3 dias**, mesmo com 55 horas decorridas:

```text theme={"system"}
from 2023-04-15 (Sat) 18:11 to 2023-04-18 (Tue) 01:48
calendar days: 3 (4 counting both end dates)
weeks: 0 weeks and 3 days
calendar months: 0 months and 3 days
elapsed: 2d 7h 37m
```

O `resolve` diz a regra que usou. "Last Saturday" é o último sábado **estritamente antes** da data de referência, e "next Friday" a primeira sexta estritamente depois; expressões maiores que uma semana ("3 weeks ago") vêm marcadas como aproximadas, porque as pessoas querem dizer os dias em volta.

## Notas

* Deslocamentos são limitados a ±100 000 unidades; uma data inválida ou uma expressão desconhecida é um erro que diz o que se esperava, nunca um chute.
* Os verbos também aceitam argumentos planos (`{"from":"2023-04-01","to":"2023-04-22"}` é um `diff`).
* A orientação de memória dada ao agente manda usar o `@date` em vez de contar dias por conta própria; veja [Memória](/pt/context/bootstrap-memory).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.