Skip to content
Menu

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 --json

Output

{
  "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 --json

Output

{
  "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
commandsLists every command the module offers.
selfcheckChecks the installed file and the database, applies pending database updates and lists any problems in plain words.
calendar addCreates a calendar for a person or a resource, with its time zone.
calendar updateChanges a calendar's name, time zone or owner.
calendar getReturns one calendar with its working hours and imported busy time.
calendar listLists the calendars.
availability setReplaces a calendar's weekly working hours and days off.
busy importStores busy time the bot read from a connected calendar, for one calendar and one window.
freeReturns the free working time on each calendar, in local time and in UTC.
plan proposePuts tasks into free working time and returns the plan, what did not fit and any rule it breaks. Nothing is stored.
plan checkChecks a plan against the current tasks and calendars and lists every rule it breaks.
plan modelReturns the same planning question as a model the Constraints module can solve.
plan commitStores the approved plan as a new version, and refuses if a task or a calendar changed since it was proposed.
plan cloneCopies a plan to a new name so an alternative can be tried without touching the original.
plan getReturns one stored version of a plan.
plan listLists the stored plans.
plan historyReturns the versions of a plan and who stored each one.
plan diffLists the blocks added, removed and moved between two versions of a plan.
plan task-updatesReturns the task updates for the bot to pass to the Tasks module. It never changes a due date.
plan holdsReturns the calendar holds to create, keep or cancel for a stored plan.
holds recordRecords which calendar events the bot created or canceled, so nothing is proposed twice.
holds listLists 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.