| name | calendar-mgmt |
| description | Google Calendar integration for end-user schedule management at runtime.
Use when the user wants to view, create, update, or delete calendar events, or get a week summary
("show my schedule", "book a meeting tomorrow at 3pm", "what's on my calendar this week").
MVP supports Google Calendar API (OAuth2). On first use, guide Google Cloud OAuth setup,
collect client_secret via hidden shell prompt, run setup.py --oauth, and store tokens in
~/.libragent/calendar_config.json. Not for LibrAgent agent cron automation (schedule / session-schedule).
Triggers on: "일정 보여줘", "캘린더 확인", "미팅 예약", "show my calendar", "schedule a meeting".
|
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
| Skill | Use for |
|---|
| schedule / session-schedule | Wake an assistant on a cron (automation harness) |
| email-integration | Mail read/send (separate OAuth; IMAP, not Gmail API) |
| recruit / boost | Create or strengthen assistant configurations |
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"
| Exit code | Meaning | Next step |
|---|
0 | Connected | Step 3 |
1 | Not configured | Step 2 |
2 | Incomplete / expired / corrupt | Step 2 (see action in JSON) |
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:
- User creates a Desktop OAuth client in Google Cloud (Calendar API enabled).
- Collect
client_id in chat (not secret).
- Hidden prompt → set
LIBRAGENT_GOOGLE_CLIENT_SECRET.
- 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:
| Action | When | Command |
|---|
week_summary | "이번 주 일정", "my week" | --action week_summary [--timezone Asia/Seoul] |
list_events | Range listing | --action list_events --from ISO --to ISO [--limit N] |
get_event | One event by ID | --action get_event --event-id ID |
create_event | Book / schedule | --action create_event --title T --start ISO --end ISO [--location L] [--description D] [--attendees a@b.com,c@d.com] |
update_event | Reschedule / edit | --action update_event --event-id ID [--title] [--start] [--end] ... |
delete_event | Cancel | --action delete_event --event-id ID |
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
| Step | Tool |
|---|
| Validate config | workspace__runCommand → validate_config.py |
| Setup / OAuth | workspace__runCommand → setup.py |
| Calendar ops | workspace__runCommand → calendar_cli.py |
| Open OAuth help URL | browser (optional, user-facing docs only) |
References
