Gcalcli Calendar

--- name: gcalcli-calendar description: "Google Calendar via gcalcli: today-only agenda by default, bounded meaning-first lookup via agenda scans, and fast create/delete with verification--optimized for low tool calls and minimal output." metadata: {"openclaw":{"emoji":"📅","requires":{"bins":["gcalcli"]}}} --- # gcalcli-calendar Use `gcalcli` to read/search/manage Google Calendar with minimal tool calls and minimal output. ## Rules ### CLI flag placement (critical) - Global flags (`--nocolor`, `--calendar`) go BEFORE the subcommand. - Subcommand-specific flags go AFTER the subcommand name. - Example: `gcalcli --nocolor delete --iamaexpert "query" start end` — NOT `gcalcli --nocolor --iamaexpert delete ...`. - This applies to ALL subcommand flags: `--iamaexpert` (delete), `--noprompt`/`--allday` (add), `--use-legacy-import` (import), etc. ### Output & language - Don't print CLI commands/flags/tool details unless the user explicitly asks (e.g. "show commands used", "/debug", "/commands"). - If asked for commands: print ALL executed commands in order (including retries) and nothing else. - Don't mix languages within one reply. - Be concise. No scope unless nothing found. ### Dates & formatting - Human-friendly dates by default. ISO only if explicitly requested. - Don't quote event titles unless needed to disambiguate. ### Calendar scope - Trust gcalcli config (default/ignore calendars). Don't broaden scope unless user asks "across all calendars" or results are clearly wrong. ### Agenda (today-only by default) - If user asks "agenda" without a period, return today only. - Expand only if explicitly asked (tomorrow / next N days / date range). ### Weekday requests (no mental math) If user says "on Monday/Tuesday/..." without a date: 1) fetch next 14 days agenda once, 2) pick matching day/event from tool output, 3) proceed (or disambiguate if multiple). ### Finding events: prefer deterministic agenda scan (meaning-first) When locating events to cancel/delete/edit: - Prefer `agenda` over `search`. - Use a bounded window and match events by meaning (semantic match) rather than exact text. - Default locate windows: - If user gives an exact date: scan that day only. - If user gives a weekday: scan next 14 days. - If user gives only meaning words ("train", "lecture", etc.) with no date: scan next 30 days first. - If still not found: expand to 180 days and say so only if still empty. Use gcalcli `search` only as a fallback when: - the time window would be too large to scan via agenda (token-heavy), or - the user explicitly asked to "search". ### Search (bounded) - Default search window: next ~180 days (unless user specified otherwise). - If no matches: say "No matches in next ~6 months (->)" and offer to expand. - Show scope only when nothing is found. ### Tool efficiency - Default: use `--nocolor` to reduce formatting noise and tokens. - Use `--tsv` only if you must parse/dedupe/sort. ## Actions policy (optimized for conversational speed) This skill is designed for personal assistant use where the user expects fast, low-friction calendar management. The confirmation policy below is an intentional UX choice — see README.md for rationale and safety guards. ### Unambiguous actions: execute immediately For cancel/delete/edit actions, skip confirmation when ALL of these hold: - The user explicitly requested the action (e.g. "delete my dentist appointment"). - Exactly one event matches in a tight time window. - The match is unambiguous (single clear result on an exact date, or user specified date+time). ### Ambiguous actions: always ask first If multiple candidates match, or the match is uncertain: - Ask a short disambiguation question listing the candidates (1-3 lines) and wait for the user's choice. ### Create events: overlap check MUST be cross-calendar (non-ignored scope) When creating an event: - Always run a best-effort overlap check across ALL non-ignored calendars by scanning agenda WITHOUT `--calendar`. - This ensures overlaps are detected even if the new event is created into a specific calendar. - If overlap exists with busy events: - Ask for confirmation before creating. - If no overlap: - Create immediately. ### Choose the right create method - **`add`** — default for one-off events. Supports `--allday`, `--reminder`, `--noprompt`. Does NOT support recurrence or free/busy (transparency). - **`import` via stdin** — use ONLY when you need recurrence (RRULE) or free/busy (TRANSP:TRANSPARENT). Pipe ICS content via stdin; NEVER write temp .ics files (working directory is unreliable in exec sandbox). - **`quick`** — avoid unless user explicitly asks for natural-language add. Less deterministic. ### Deletes must be verified - Use non-interactive delete with `--iamaexpert` (a `delete` subcommand flag — goes AFTER `delete`). This is gcalcli's built-in flag for non-interactive/scripted deletion. - Always verify via agenda in the same tight window after deletion. - If verification still shows the event, do one retry with `--refresh`. - Never claim success unless verification confirms the event is gone. ## Canonical commands ### Agenda (deterministic listing) - Today: `gcalcli --nocolor agenda today tomorrow` - Next 14d (weekday resolution): `gcalcli --nocolor agenda today +14d` - Next 30d (meaning-first locate): `gcalcli --nocolor agenda today +30d` - Custom: `gcalcli --nocolor agenda ` ### Search (fallback / explicit request) - Default (~6 months): `gcalcli --nocolor search "" today +180d` - Custom: `gcalcli --nocolor search "" ` ### Create — `add` (one-off events) - Overlap preflight (tight, cross-calendar): - `gcalcli --nocolor agenda ` - IMPORTANT: do NOT add `--calendar` here; overlaps must be checked across all non-ignored calendars. - Timed event: - `gcalcli --nocolor --calendar "" add --noprompt --title "