The "file over app" philosophy for calendars.

~/caldir/ ├── home/ │ └── 2025-03-25T0900__dentist.ics └── work/ ├── 2025-03-20T1500__client-call.ics └── 2025-03-26T1400__sprint-planning.ics 

Calendars already have an open format (.ics files) but they're hidden behind APIs and proprietary sync layers.

Caldir connects to any provider and puts your calendar data on disk, so that you can:

Search it

grep -l "holiday" ~/caldir/**/*.ics

Script it

# Daily schedule in your terminal echo "Today:" && ls ~/caldir/*/$(date +%Y-%m-%d)*

Manage it with your AI agent

claude "Move my Thursday meetings to Friday" # Claude reads, renames, and edits the .ics files directly

Keep your data portable

# Migrate events from Outlook to Google Calendar mv ~/caldir/outlook/*.ics ~/caldir/google/

# Install caldir curl -sSf https://caldir.org/install.sh | sh # Connect and follow the instructions in the CLI: caldir connect google # or "caldir connect icloud", "caldir connect caldav"... # Sync your calendar events caldir sync # Your calendar events are now in ~/caldir

cargo install --path caldir-cli cargo install --path caldir-provider-google # Google Calendar cargo install --path caldir-provider-icloud # Apple iCloud

Caldir syncs through providers — small plugin binaries that talk to calendar services. It currently supports:

• Google (caldir-provider-google)
• iCloud (caldir-provider-icloud)
• Outlook (caldir-provider-outlook)
• CalDAV (caldir-provider-caldav)

A provider is just an executable named caldir-provider-{name} that speaks JSON over stdin/stdout. Anyone can create one.

Once a provider is connected, you can communicate with it using caldir's CLI commands:

• caldir pull -- download remote changes to local
• caldir push -- upload local changes to remote (including deletions)
• caldir sync -- both, in one command
• caldir status -- show pending changes in either direction

Create event

caldir new # Interactive mode (for humans) caldir new "Meeting" --start 2025-03-20T15:00 # Non-interactive mode (for agents)

View events

caldir events # Next 3 days caldir today # Today's events caldir week # This week (through Sunday)

Sync with provider

caldir status # Show pending changes caldir sync # Push/Pull changes

Caldir's global settings are stored in in your system's config directory:

# ~/.config/caldir/config.toml (Linux) # ~/Library/Application Support/caldir/config.toml (macOS) calendar_dir = "~/caldir" default_calendar = "personal"

Your calendar-specific settings are stored in each calendar's directory:

# ~/caldir/personal/.caldir/config.toml name = "Personal" color = "#4285f4" [remote] provider = "google" google_account = "me@gmail.com" google_calendar_id = "primary"

For more details, check out the full documentation.