caldav-calendar

clawdbot's avatarfrom clawdbot

Sync and query CalDAV calendars (iCloud, Google, Fastmail, Nextcloud, etc.) using vdirsyncer + khal. Works on Linux.

⭐2stars🔀0forks📁View on GitHub🕐Updated Jan 8, 2026
[Meeting Productivity]

When & Why to Use This Skill

The CalDAV Calendar skill provides a powerful command-line interface for synchronizing and managing calendars across multiple providers such as iCloud, Google, Fastmail, and Nextcloud. By integrating vdirsyncer for robust background synchronization and khal for event manipulation, it enables users and AI agents to query schedules, search for specific events, and create new appointments directly within a Linux environment. This tool is essential for streamlining scheduling workflows and maintaining a unified view of professional and personal commitments.

Use Cases

  • Unified Schedule Management: Consolidate multiple calendar accounts (e.g., Work, Personal, Shared) into a single searchable interface for a comprehensive daily or weekly overview.
  • AI-Driven Appointment Scheduling: Empower AI agents to check your real-time availability and automatically create new calendar events or reminders using natural language.
  • Automated Meeting Summaries: Script the retrieval of upcoming events to generate automated daily briefings or preparation notes for scheduled meetings.
  • Headless Calendar Integration: Integrate calendar data into DevOps or automation workflows, allowing for time-based task execution or status updates based on your schedule.
namecaldav-calendar
descriptionSync and query CalDAV calendars (iCloud, Google, Fastmail, Nextcloud, etc.) using vdirsyncer + khal. Works on Linux.
metadata{"clawdbot":{"emoji":"📅","os":["linux"],"requires":{"bins":["vdirsyncer","khal"]},"install":[{"id":"apt","kind":"apt","packages":["vdirsyncer","khal"],"bins":["vdirsyncer","khal"],"label":"Install vdirsyncer + khal via apt"}]}}

CalDAV Calendar (vdirsyncer + khal)

vdirsyncer syncs CalDAV calendars to local .ics files. khal reads and writes them.

Sync First

Always sync before querying or after making changes:

vdirsyncer sync

View Events

khal list                        # Today
khal list today 7d               # Next 7 days
khal list tomorrow               # Tomorrow
khal list 2026-01-15 2026-01-20  # Date range
khal list -a Work today          # Specific calendar

Search

khal search "meeting"
khal search "dentist" --format "{start-date} {title}"

Create Events

khal new 2026-01-15 10:00 11:00 "Meeting title"
khal new 2026-01-15 "All day event"
khal new tomorrow 14:00 15:30 "Call" -a Work
khal new 2026-01-15 10:00 11:00 "With notes" :: Description goes here

After creating, sync to push changes:

vdirsyncer sync

Edit Events (interactive)

khal edit is interactive — requires a TTY. Use tmux if automating:

khal edit "search term"
khal edit -a CalendarName "search term"
khal edit --show-past "old event"

Menu options:

  • s → edit summary
  • d → edit description
  • t → edit datetime range
  • l → edit location
  • D → delete event
  • n → skip (save changes, next match)
  • q → quit

After editing, sync:

vdirsyncer sync

Delete Events

Use khal edit, then press D to delete.

Output Formats

For scripting:

khal list --format "{start-date} {start-time}-{end-time} {title}" today 7d
khal list --format "{uid} | {title} | {calendar}" today

Placeholders: {title}, {description}, {start}, {end}, {start-date}, {start-time}, {end-date}, {end-time}, {location}, {calendar}, {uid}

Caching

khal caches events in ~/.local/share/khal/khal.db. If data looks stale after syncing:

rm ~/.local/share/khal/khal.db

Initial Setup

1. Configure vdirsyncer (~/.config/vdirsyncer/config)

Example for iCloud:

[general]
status_path = "~/.local/share/vdirsyncer/status/"

[pair icloud_calendar]
a = "icloud_remote"
b = "icloud_local"
collections = ["from a", "from b"]
conflict_resolution = "a wins"

[storage icloud_remote]
type = "caldav"
url = "https://caldav.icloud.com/"
username = "your@icloud.com"
password.fetch = ["command", "cat", "~/.config/vdirsyncer/icloud_password"]

[storage icloud_local]
type = "filesystem"
path = "~/.local/share/vdirsyncer/calendars/"
fileext = ".ics"

Provider URLs:

  • iCloud: https://caldav.icloud.com/
  • Google: Use google_calendar storage type
  • Fastmail: https://caldav.fastmail.com/dav/calendars/user/EMAIL/
  • Nextcloud: https://YOUR.CLOUD/remote.php/dav/calendars/USERNAME/

2. Configure khal (~/.config/khal/config)

[calendars]
[[my_calendars]]
path = ~/.local/share/vdirsyncer/calendars/*
type = discover

[default]
default_calendar = Home
highlight_event_days = True

[locale]
timeformat = %H:%M
dateformat = %Y-%m-%d

3. Discover and sync

vdirsyncer discover   # First time only
vdirsyncer sync
caldav-calendar – AI Agent Skills | Claude Skills