Scheduling module
Keeps calendars with time zones, working hours and busy time, and plans tasks into free working time for you to approve.
On this page
What it is for
Keeps calendars with time zones, working hours and busy time, and plans tasks into free working time for you to approve.
- You want to know when open work could get done within working hours.
- You want to see free time across people in different time zones.
- You want planned work held on a calendar after you approve it.
- You want to try a different plan without losing the one you approved.
Ask your bot
You do not type commands. Ask in plain words and the bot runs the module for you.
- You ask
- Plan next week's open tasks into my working hours and show me the plan before anything goes on my calendar.
- What you get back
- The bot shows the proposed blocks of time in a Grok Bot Page, with any task that did not fit and why. Nothing is stored or put on a calendar until you approve.
What the bot does with it
- The bot sets up a calendar for each person or resource, with a time zone and working hours.
- If your calendar is connected, the bot reads your busy time through its own connection and hands it to the module. The module never contacts a calendar service.
- It proposes a plan that puts open tasks into free working time and checks the plan with a separate checker.
- It stores a plan only after you approve that exact plan. A stored version is never edited.
- From a stored plan it gets the task updates to pass to the Tasks module and the calendar holds it may create for you. It creates or cancels a calendar event only after you approve.
What it stores
Calendars, working hours, imported busy time, every stored version of a plan and the record of calendar holds live in one SQLite file, scheduling/scheduling.sqlite, in the bot's Ambitious folder (/workspace/ambitious by default). Stored plan versions are added and never edited.
The module has no screens of its own. It reads JSON, writes JSON, and keeps its data under /workspace/ambitious on the bot's computer. It never sends data anywhere.
Command reference
For the technically curious. You will rarely type these yourself; the bot runs them. Every command answers with the same envelope: whether it worked, which module and command ran, the data, and a list of errors with a hint for each. Open an example to see the command and its output.
ExampleAdd a calendar for one person, with its time zone. Working hours are set in a second step.
Command
echo '{"id":"front-desk","name":"Front desk","tz":"America/Chicago","idem_key":"add-front-desk"}' | ambitious-scheduling calendar add --jsonOutput
{
"ok": true,
"schemaVersion": 1,
"module": "scheduling",
"command": "calendar add",
"data": {
"calendar": {
"id": "front-desk",
"version": 1,
"name": "Front desk",
"tz": "America/Chicago",
"kind": "person",
"person_ref": null,
"rules": [],
"exceptions": []
}
},
"errors": [],
"meta": { "now": "2026-03-02T09:00:00.000Z", "seed": 7, "version": "0.1.0" }
}ExampleRead the free working time on that calendar for two days, after its hours were set to weekdays from 09:00 to 17:00. Each stretch is given in UTC and in local time.
Command
echo '{"calendar_ids":["front-desk"],"from":"2026-03-02T00:00:00-06:00","to":"2026-03-04T00:00:00-06:00","min_minutes":60}' | ambitious-scheduling free --jsonOutput
{
"ok": true,
"schemaVersion": 1,
"module": "scheduling",
"command": "free",
"data": {
"calendars": [
{
"calendar_id": "front-desk",
"tz": "America/Chicago",
"free": [
{
"start": "2026-03-02T15:00:00.000Z",
"end": "2026-03-02T23:00:00.000Z",
"local_start": "2026-03-02T09:00:00-06:00",
"local_end": "2026-03-02T17:00:00-06:00",
"minutes": 480
},
{
"start": "2026-03-03T15:00:00.000Z",
"end": "2026-03-03T23:00:00.000Z",
"local_start": "2026-03-03T09:00:00-06:00",
"local_end": "2026-03-03T17:00:00-06:00",
"minutes": 480
}
],
"free_minutes": 960,
"notes": []
}
],
"tzdata": "2026c"
},
"errors": [],
"meta": { "now": "2026-03-02T09:00:00.000Z", "seed": 7, "version": "0.1.0" }
}Show every command
| commands | Lists every command the module offers. |
|---|---|
| selfcheck | Checks the installed file and the database, applies pending database updates and lists any problems in plain words. |
| calendar add | Creates a calendar for a person or a resource, with its time zone. |
| calendar update | Changes a calendar's name, time zone or owner. |
| calendar get | Returns one calendar with its working hours and imported busy time. |
| calendar list | Lists the calendars. |
| availability set | Replaces a calendar's weekly working hours and days off. |
| busy import | Stores busy time the bot read from a connected calendar, for one calendar and one window. |
| free | Returns the free working time on each calendar, in local time and in UTC. |
| plan propose | Puts tasks into free working time and returns the plan, what did not fit and any rule it breaks. Nothing is stored. |
| plan check | Checks a plan against the current tasks and calendars and lists every rule it breaks. |
| plan model | Returns the same planning question as a model the Constraints module can solve. |
| plan commit | Stores the approved plan as a new version, and refuses if a task or a calendar changed since it was proposed. |
| plan clone | Copies a plan to a new name so an alternative can be tried without touching the original. |
| plan get | Returns one stored version of a plan. |
| plan list | Lists the stored plans. |
| plan history | Returns the versions of a plan and who stored each one. |
| plan diff | Lists the blocks added, removed and moved between two versions of a plan. |
| plan task-updates | Returns the task updates for the bot to pass to the Tasks module. It never changes a due date. |
| plan holds | Returns the calendar holds to create, keep or cancel for a stored plan. |
| holds record | Records which calendar events the bot created or canceled, so nothing is proposed twice. |
| holds list | Lists the recorded calendar events for a plan. |
Source and releases
The module is open source under the Apache license. Each release carries one bundled file and its checksums; the bot installs it for you.