Calendar Mgmt

Calendar Management

Manage the user's Google Calendar from LibrAgent — read and write events, summarize the week.

This is an end-user daily work skill (like email-integration, telegram-cli, x-cli). It is not for LibrAgent internal development or agent-only cron tasks.

Not This Skill

CalDAV (Nextcloud, Apple, Fastmail) is planned for a later release. MVP is Google Calendar API only.

Path conventions

Paths are relative to this skill's Base Directory. Replace <skill-base-dir> with its absolute path in commands.

Security (mandatory)

• NEVER ask for client_secret, access tokens, or refresh tokens in chat
• NEVER display or repeat ~/.libragent/calendar_config.json
• Collect client_secret only via a single hidden shell prompt (requireUserInput=true, inputType=password), then pass --client-secret-env LIBRAGENT_GOOGLE_CLIENT_SECRET
• If the user pastes a secret in chat, do not echo it — run setup immediately

Prerequisites

pip install google-auth google-auth-oauthlib google-api-python-client

On Linux/macOS use pip3 if pip is unavailable.

Workflow

1. Detect config

python "<skill-base-dir>/scripts/validate_config.py"

2. Setup (first time or re-auth)

See references/google-setup.md for Google Cloud Console steps and references/setup-flow.md for the LibrAgent hidden-prompt pattern.

Summary:

1. User creates a Desktop OAuth client in Google Cloud (Calendar API enabled).
2. Collect client_id in chat (not secret).
3. Hidden prompt → set LIBRAGENT_GOOGLE_CLIENT_SECRET.
4. Run OAuth:

python "<skill-base-dir>/scripts/setup.py" \
  --client-id "YOUR_CLIENT_ID.apps.googleusercontent.com" \
  --client-secret-env LIBRAGENT_GOOGLE_CLIENT_SECRET \
  --oauth

Re-auth only (credentials already saved):

python "<skill-base-dir>/scripts/setup.py" --oauth

Reset and reconnect:

python "<skill-base-dir>/scripts/setup.py" \
  --reset \
  --client-id "..." \
  --client-secret-env LIBRAGENT_GOOGLE_CLIENT_SECRET \
  --oauth

A browser window opens for Google consent. Tokens persist under ~/.libragent/calendar_config.json.

3. Dispatch action

Classify the request and call calendar_cli.py:

Use RFC 3339 datetimes (e.g. 2026-06-12T15:00:00+09:00). For all-day events add --all-day and use YYYY-MM-DD dates.

Examples: references/request-patterns.md.

Before create/update/delete: confirm title, time, and timezone with the user when the request is ambiguous.

4. Present results

Format for humans per references/output-format.md. Errors: references/error-handling.md.

Config shape

{
  "provider": "google",
  "google": {
    "client_id": "...",
    "client_secret": "...",
    "tokens": { }
  },
  "caldav": null
}

caldav is reserved for a future release.

Guidelines

• User calendar, not agent cron — distinguish from schedule skill.
• OAuth is multi-step — similar friction to telegram-cli, not email-integration app passwords.
• No Gmail API synergy in v1 — email uses IMAP; cross-skill "mail → event" uses agent reasoning, not shared tokens.
• Confirm destructive actions — delete and attendee-affecting updates.
• Timezone explicit — ask or infer user timezone for week_summary and new events.

Builtin Tools

References

• google-setup.md — Google Cloud OAuth client setup
• setup-flow.md — hidden prompt + setup commands
• request-patterns.md — natural language → actions
• output-format.md — presentation guidelines
• error-handling.md — recovery steps
• caldav-setup.md — future CalDAV (not in MVP)