Gcalcli Calendar 3.0.0

---

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 "