neuroskill-com/neuroskill-calendar

NeuroSkill Calendar

Reads calendar events directly from the operating system:

| Platform | Source | |----------|--------| | macOS | Apple EventKit — all calendars synced to Calendar.app (iCloud, Google, Exchange, local) | | Linux | .ics files from GNOME Calendar, Evolution, KOrganizer, Thunderbird Lightning, ~/Calendars/ | | Windows | .ics files from Outlook / Windows Calendar app paths |

---

LLM Tool Calls

{"command": "calendar_events", "args": {"start_utc": 1774396800, "end_utc": 1774483200}}
{"command": "calendar_status"}
{"command": "calendar_request_permission"}

Getting timestamps: use the date tool first to get now_unix, then compute ranges:

• Today: start_utc = now_unix - (now_unix % 86400), end_utc = start_utc + 86400
• Next 7 days: start_utc = now_unix, end_utc = now_unix + 604800
• This week (Mon–Sun): align to Monday midnight

---

Commands

calendar_events

Fetch all events overlapping [start_utc, end_utc].

| Field | Type | Required | Description | |-------|------|----------|-------------| | start_utc | i64 | ✓ | Range start (UTC unix seconds, inclusive) | | end_utc | i64 | ✓ | Range end (UTC unix seconds, inclusive) |

Response:

{
  "events": [
    {
      "id":          "[email protected]",
      "title":       "Sprint Review",
      "start_utc":   1774468800,
      "end_utc":     1774472400,
      "all_day":     false,
      "location":    "Conference Room B",
      "notes":       "Bring laptop. Demo Q2 features.",
      "calendar":    "Work",
      "status":      "confirmed",
      "recurrence":  "FREQ=WEEKLY;BYDAY=WE"
    }
  ],
  "count": 1
}

status is one of "confirmed", "tentative", "cancelled". recurrence is the raw RRULE string (not expanded — only the base instance is returned). all_day events have start_utc at midnight UTC; end_utc is the next midnight.

calendar_status

Check whether the app has permission to read calendars.

Response:

{ "status": "authorized", "platform": "macos" }

status values: "authorized" | "not_determined" | "denied" | "restricted"

If status is "not_determined", suggest running calendar_request_permission. If status is "denied", direct the user to System Settings → Privacy & Security → Calendars.

calendar_request_permission

Show the macOS system permission dialog. No-op on Linux/Windows (always authorized).

Response:

{ "granted": true, "status": "authorized" }

---

CLI Examples

npx neuroskill calendar                            # events: next 7 days
npx neuroskill calendar --start 1774396800 --end 1774483200
npx neuroskill calendar --json
npx neuroskill calendar --json | jq '.events[] | {title, start_utc, calendar}'
npx neuroskill calendar status                     # auth status + platform
npx neuroskill calendar permission                 # macOS: request system dialog

---

HTTP API

POST /v1/calendar/events      { "start_utc": 1774396800, "end_utc": 1774483200 }
GET  /v1/calendar/status
POST /v1/calendar/permission

---

Common Queries

"What do I have today?"

{"command": "calendar_events", "args": {"start_utc": <today_start>, "end_utc": <today_end>}}

"What's my next meeting?" Fetch events for the next few hours, sort by start_utc, return the first future one.

"Am I free at 3pm?" Fetch events for the 1-hour window around 3pm, check if any overlap.

"How many meetings do I have this week?" Fetch [monday_00:00, sunday_23:59], count non-cancelled events.

"What's on my calendar right now?" start_utc = now, end_utc = now + 3600; a non-empty result means something is happening.

---

Access Troubleshooting

| status | Meaning | Fix | |----------|---------|-----| | not_determined | Never asked | Run calendar_request_permission | | authorized | All good | — | | denied | User declined | System Settings → Privacy & Security → Calendars → enable Skill | | restricted | MDM/parental controls | Contact device administrator |

If calendar_events returns {"error": "calendar_write_only_access"}, the user chose "Add Events Only" in the permission dialog. Run calendar_request_permission again to prompt for full read access, or direct them to System Settings → Calendars.

On Linux and Windows access is always authorized; if events is empty, no .ics files were found in the standard locations. The user can place exported .ics files in ~/Calendars/.