Cal CLI

Apple Calendar directly in your Codex chats on macOS.

Check appointments and availability, then create, edit, reschedule, or delete the event you request. No separate calendar viewer, application window, or background service.

Cal CLI uses Apple’s public EventKit framework and the calendar accounts already configured on your Mac.

Klarhet Studio: https://klarhetstudio.com

Local EventKit connection · Fresh calendar reads · Explicit writes · No telemetry

What you can do

Ask naturally:

“Am I free between ten and eleven tomorrow?”

“Book a dentist appointment next Tuesday at two for forty-five minutes.”

“Move that appointment to Wednesday at three.”

“Delete only this Friday’s occurrence of my weekly meeting.”

Cal CLI queries current calendar data when needed. It does not continuously monitor your calendar.

How it works

Cal CLI connects Codex to Apple Calendar through EventKit on your Mac.

It works with the calendar accounts already configured in macOS, including iCloud, local calendars, and other accounts supported by EventKit.

The local helper has no network client, telemetry, stored calendar index, or direct Calendar-database access. Apple Calendar continues to perform its normal account synchronization.

Calendar data returned to your assistant becomes part of that assistant’s tool context and is subject to its data-handling settings.

Install

Requires:

• Codex app on macOS 13 or newer
• Python 3.9 or newer
• Xcode Command Line Tools

A separate Codex CLI installation is not required.

Install through the Codex app

1. Open Plugins and choose Add plugin marketplace.
2. Set Source to claessee/cal-cli.
3. Set Git ref to main and leave Sparse paths empty.
4. Click Add marketplace, then select Cal CLI and install it.
5. Accept the offer of setup help, or ask:

“Help me set up Cal CLI with its onboarding skill.”

Setup checks the local helper, Calendar permission, time zone, and saved availability calendars. It installs the helper if needed.

If your existing calendar selection is still valid, setup preserves and verifies it rather than asking you to configure it again. Calendar permission or a new selection is requested only when needed.

You do not need to open the repository as a Codex project first.

Setup verifies the plugin tools immediately. If they are available, you can use Cal CLI in the current chat. Start a new chat or restart the app only if the tools are unavailable or still expose an older version.

If swiftc is unavailable, install the Xcode Command Line Tools:

xcode-select --install

Availability calendars

During first setup, choose the calendars that represent your actual commitments.

Include shared or read-only calendars where appropriate. Leave holiday, sports, or similar subscription calendars out unless they should block your availability.

Your selection is stored locally in:

~/.config/cal-cli/settings.json

The Mac’s default calendar determines the default destination for newly created appointments. It does not determine which calendars count toward your availability.

General appointment reads, availability checks, and booking or rescheduling conflict checks use your saved selection automatically. Results identify the calendars that were checked.

To change the selection later:

~/.local/bin/cal-cli configure

You can also ask the connected assistant to list your calendars and save your choices.

Preferences belong to each Mac user. Cloning the repository copies the code; cal-cli setup stores that user’s configuration locally.

If no selection has been saved, general reads and conflict checks return calendar_selection_required rather than a free-time answer.

If a selected calendar disappears, the check fails and asks you to select calendars again. New calendars are not added automatically. Renaming a calendar retains its selection as long as its ID remains unchanged.

A specific request can override the saved calendar scope with explicit calendar IDs without changing your preferences.

Calendar access

Cal CLI needs Calendar access to inspect existing appointments and make changes you request.

It does not request Reminders access or Full Disk Access.

If Calendar access was previously denied, enable it under:

System Settings → Privacy & Security → Calendars

Time zone

Cal CLI uses the Mac’s time zone unless you configure another IANA time-zone name.

For a terminal installation, for example:

python3 scripts/install.py --timezone Europe/Lisbon

The setting is stored in your local Cal CLI configuration outside the repository.

Optional installation paths

Install the helper from Terminal first

If you prefer to build and configure the helper before adding the Codex plugin:

git clone https://github.com/claessee/cal-cli.git
cd cal-cli
python3 scripts/install.py
~/.local/bin/cal-cli setup

Allow Calendar access in the macOS prompt if it has not already been granted.

On first setup, select the calendars containing commitments that should affect your availability. Running setup again verifies and reuses a valid saved selection without prompting.

Then add Cal CLI through the Codex app. Its onboarding reuses the Calendar permission and availability selection already completed in Terminal.

Register the plugin with Codex CLI

If you already use Codex CLI:

codex plugin marketplace add claessee/cal-cli
codex plugin add cal-cli@cal-cli-plugins

Verify the connection by asking Codex to check Calendar connection status and list your selected calendars.

Use Cal CLI as a direct MCP server

Other MCP clients can run:

~/.local/bin/cal-cli mcp

For a direct Codex MCP connection instead of the plugin:

codex mcp add cal-cli -- ~/.local/bin/cal-cli mcp

Use either the plugin or the direct MCP connection, not both.

The MCP server exposes nine tools:

calendar_status, list_calendars, configure_calendars, list_events, get_event, check_availability, create_event, update_event, and delete_event.

configure_calendars changes only local preferences. It requires the user’s chosen calendar IDs and confirm: true; it does not modify Calendar accounts or appointments.

Behavior and limits

Cal CLI is deliberately conservative when changing calendar data.

• Fresh reads. Event listings query current Calendar data. Listings report total counts and truncation, while availability checks inspect all matching events rather than only the displayed page.
• Revision-aware changes. Event references include the calendar, event, and occurrence date. Edits and deletions require a revision from a fresh read, so externally changed appointments are rejected.
• Explicit writes. Writes require confirm: true, representing a user-requested change. Results include verified read-back or an explicit committed-write error that should not be blindly retried.
• Conflict checking. Rescheduling rejects conflicts by default while excluding the appointment being moved. An explicitly requested overlap can override that check.
• Recurring events. Edits support the selected occurrence (this) or that occurrence and future occurrences (future). Whole-series operations are not exposed.
• Recurring creation. Daily, weekly, monthly, and yearly recurrence is supported with an optional count or end. Automatic conflict checking covers the first occurrence only; later occurrences must be examined separately.
• All-day events. These use floating calendar dates with an exclusive end date. EventKit represents them in the Mac’s system time zone independently of Cal CLI’s configured time zone. See Apple’s EventKit date documentation.
• Query range. Queries are limited to 366 days per request. Event listings return up to 500 rows and explicitly report truncation.
• Notes. Notes are omitted unless requested.
• Not exposed. Invitation or attendee management, calendar sharing, travel-time alerts, and calendar deletion are not available to the assistant.
• Mac-local access. A GitHub marketplace plugin does not independently give a cloud chat, Windows computer, or phone access to that Mac’s calendar.

The standalone helper is installed under:

~/.local/share/cal-cli

with the launcher at:

~/.local/bin/cal-cli

Source builds are ad-hoc signed. Rebuilding or changing the hosting application may require Calendar permission again. A stable Developer ID can be supplied with CAL_CLI_SIGN_IDENTITY for a signed release.

Privacy

The helper has:

• no network client
• no telemetry
• no stored calendar index
• no direct Calendar-database access

It reads and writes through EventKit. Apple Calendar performs normal account synchronization.

No Cal CLI developer server receives calendar data.

Local preferences contain configuration only, not an appointment archive.

Calendar data returned to your assistant becomes part of that assistant’s tool context and is subject to its data-handling settings. It is not guaranteed to remain only on your Mac.

Development and verification

Build the native EventKit engine and run the repository checks:

swift build --product cal-cli-engine
python3 scripts/check.py

Pure tests do not read or change Calendar.

After Calendar access has been granted, explicit live verification can create a dedicated private verification calendar, test ordinary appointments, conflicts, stale revisions, recurring occurrence edits and deletion, and daylight-saving boundaries, then remove that calendar:

CAL_CLI_VERIFY_LIVE=1 ~/.local/bin/cal-cli verify-live

Never run integration fixtures inside an existing user calendar.

If cleanup fails, the result identifies the temporary verification calendar so that only that named verification calendar can be removed.

Updates

In the Codex app, refresh the Cal CLI marketplace and ask for help updating Cal CLI with its onboarding skill.

If you manage the helper from a checkout, pull the new source and rerun:

python3 scripts/install.py

The installer preserves your time zone and calendar selection and keeps the previous native binary for recovery. Setup verifies valid existing choices instead of asking for them again.

Start a new chat or restart the app only if the tools still expose the previous version.

Codex CLI users can refresh the marketplace with:

codex plugin marketplace upgrade cal-cli-plugins

Removal

In the Codex app, uninstall Cal CLI from Plugins and remove its marketplace if you no longer need it.

Codex CLI users can instead run:

codex plugin remove cal-cli@cal-cli-plugins
codex plugin marketplace remove cal-cli-plugins

For a direct MCP installation:

codex mcp remove cal-cli

To remove the local helper and launcher, run from the checkout:

python3 scripts/uninstall.py

Existing appointments and Apple Calendar accounts are unaffected. macOS Calendar permissions are managed separately in System Settings.

License

MIT.

Cal CLI is an independent project and is not affiliated with Apple or OpenAI. The implementation uses public EventKit APIs and standard libraries.