Calendar export (ICS)

Pensum can export your tasks as an iCalendar (.ics) file. The file lives inside your vault, which means any tool that can read a URL or a synced file path can subscribe to it — Apple Calendar, Google Calendar, Outlook, Fantastical, and so on — and show your tasks alongside your existing events.

The export is one-way (read-only from the calendar’s side) and refreshes whenever you re-run the export command. There’s no live sync; this is intentionally simple and offline-capable.

Run the export

Three entry points, same result:

1. Command palette → Pensum: Export tasks to ICS. Writes to Pensum/Exports/tasks.ics in your vault.
2. Hotkey → bind pensum:export-tasks-ics under Settings → Hotkeys if you re-run it often.
3. MCP → vault.export_ics returns the ICS string in the response so an agent can write it wherever it likes.

A success notice tells you the file path and how many events were written.

What’s included

By default, the export includes every task with at least one date (due, scheduled, or start), and the status filter is:

• Open tasks ([ ])
• In-progress tasks ([/])
• Waiting tasks ([w])
• Completed tasks ([x]) completed in the last 30 days

The 30-day completion window keeps the calendar from being polluted by years of historical done work. Older completed tasks are skipped silently.

Each task becomes one VEVENT:

iCal property	Source
SUMMARY	Task description, with priority emoji prepended (🔼 Ship Q3 plan)
DTSTART	The task’s anchor date (due > scheduled > start, first one present)
DTEND	Anchor + 1 day (so it shows as an all-day event)
STATUS	CONFIRMED (open), COMPLETED (done), CANCELLED ([-])
DESCRIPTION	Project, tags, source file path, plus any additional dates (scheduled, defer, recurrence)
URL	obsidian://open?vault=<name>&file=<path> deep link back to the source note

Long descriptions are line-folded per RFC 5545. Special characters (,, ;, newlines) are escaped.

Subscribing in Apple Calendar

1. In Finder, navigate to <vault>/Pensum/Exports/tasks.ics.
2. Double-click. Apple Calendar prompts you to subscribe.
3. Set the auto-refresh interval (Pensum recommends Daily, since the file only changes when you re-run the export).

If you sync your vault with iCloud, the file is available on every Mac with that vault — subscribe on each device. If you use Obsidian Sync, you can also subscribe on iOS by sharing the file through Files → Add Account → Server, but this is fiddlier than just re-exporting on the device.

Subscribing in Google Calendar

Google Calendar needs an HTTPS URL — it can’t read a local file. Two paths:

1. Drop the file in a publicly-accessible location. If your vault syncs through a tool with a public URL feature (Dropbox, GitHub Pages, a personal web server), point Google Calendar at the public URL of tasks.ics. Other Settings → Add Calendar → From URL → paste the URL.
2. Use a relay tool. Services like iCloud Calendar or radicale can sync the local file to an HTTPS endpoint Google Calendar can read.

There’s no way to subscribe directly to a vault-internal file from Google Calendar — that’s a Google constraint, not a Pensum one.

Filtering what gets exported

The default filter (open + in-progress + waiting + recent completions) suits most people. To customise:

• From MCP: pass status: [" ", "/"] to vault.export_ics to export only active and in-progress (no waiting, no completed).
• From the plugin: the command currently uses the default filter — a settings panel for it is planned but not in v1.0.

Auto-refresh

The export file isn’t regenerated automatically — you re-run the command (or the hotkey) when you want it fresh. Two reasonable patterns:

• Re-export at the end of every weekly review. It takes a second; your calendar has a current snapshot for the week.
• Bind it to a hotkey and re-run on demand. Fastest workflow if you live in your calendar.

A scheduled auto-export is on the roadmap but deliberately not in v1.0 — it would need its own preferences UI and most people seem fine running it manually.

Why all-day events

Pensum tasks have dates, not date+time. Putting them on the calendar as all-day events (the iCal VALUE=DATE form) keeps them out of your timeline view while still showing in agenda and month views. If you want timed events, you’re probably looking for actual calendar items, not tasks — keep those in your calendar.

Removing the export

Delete Pensum/Exports/tasks.ics. The calendar will show its last-known state until you unsubscribe in the calendar app. There’s no Pensum-side cleanup to run.