Calendar arithmetic (@date)

Language models read dates well and count them badly: how many days between the 14th of March and the 17th of April, what day was last Saturday, what is three weeks before the 5th. @date answers those from the calendar instead of from the model’s head. Every verb is pure, offline and read-only: no file, network or credential is touched, and the tool runs in parallel with others. It counts from the current date, which CHATCLI_NOW pins for a whole run, so a conversation replayed from the past reads “last Saturday” against the right day.

<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}}' />

Verb	Arguments	What it does
`now`		the current date, weekday and time
`diff`	`from`, `to?` (default today)	calendar days, weeks plus days, calendar months plus days, and the elapsed time; it also says how many days it is counting both end dates, so an inclusive reading is never a guess
`add`	`date?` (default today), `days?`, `weeks?`, `months?`, `years?`	the date that far away (negative = earlier); a month end clamps to the last day of a shorter month, so January 31 plus one month is February 28
`weekday`	`date?`	the weekday of a date
`resolve`	`expr`, `as_of?`	`yesterday`, `tomorrow`, `last` or `next` plus a weekday, `N days\|weeks\|months\|years ago`, `in N days\|weeks\|months`, as a concrete date

Dates are read as 2023-03-14, 2023/03/14, 2023-03-14 18:11, RFC 3339, or the form @session prints (2023-03-14 (Tue) 18:11); today and now mean the current date.

What the answers say

diff reports calendar days (the later date minus the earlier one, ignoring the time of day), so a session saved on the 15th at 18:11 and a question on the 18th at 01:48 are 3 days apart even though 55 hours passed:

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

resolve states the rule it used. “Last Saturday” is the most recent Saturday strictly before the reference date, and “next Friday” the first one strictly after; expressions longer than a week (“3 weeks ago”) are labeled approximate, because people mean the days around them.

Notes

Offsets are limited to ±100 000 units; a bad date or an unknown expression is an error that says what was expected, never a guess.
The verbs also accept flat arguments ({"from":"2023-04-01","to":"2023-04-22"} is a diff).
The memory guidance given to the agent tells it to use @date instead of counting days itself; see Memory.

Get started

Documentation

Calendar arithmetic (@date)

What the answers say

Notes

​What the answers say

​Notes

What the answers say

Notes