Start here

calkit is a command-line calendar. It stores events as YAML in a git repo. You (or an agent) run one command per action. There is no AI inside the tool. It is deterministic. It is not Apple Calendar, not a hosted calendar, and not an autopilot.

​

What you can do

• Create a calendar repo (init).
• Add, edit, move, and delete events.
• Read an agenda (recurrence expanded on read).
• Import and export iCalendar (.ics).
• Serve a local month view and localhost ICS feeds.
• Snapshot history with git.
• Fire mechanical reminders (optional local cron).

​

The JSON rule

Always pass --json when a program or agent will parse stdout. Success: {"ok":true,"data":…}
Failure: {"ok":false,"error":{"code","message"}} and a nonzero exit. Human tables are for humans. See JSON output.

​

Work in a calendar repo

Every command except init needs a .calkit/ marker in this directory or an ancestor. If you see NOT_FOUND: not a calkit calendar, you are in the wrong folder — or you still need setup.

​

Mutations do not commit

add / edit / rm / mv change files. They do not make a git commit. Use calkit snapshot -m "…" when the human wants a checkpoint. Never git push unless asked.

​

Next

1. Set up a calendar if there is no .calkit/ yet.
2. Agenda once events exist.
3. Agents: For agents.