Opys Calendar Skill

A local markdown-backed calendar with CLI and optional two-way Google Calendar sync.

Security Scan

The skill appears to do what it claims — a local markdown-backed calendar with a CLI and optional Google Calendar sync — but it stores snapshots and session tokens on disk, so treat those files and Google credentials as sensitive.

Purpose & Capability

Name/description match the code and instructions: the repo provides a CLI, a React UI, an Express API server, and optional two-way Google Calendar sync. The environment variables and local files referenced (calendar.md, snapshot, sync state) are consistent with a local-first calendar with optional Google OAuth.

Instruction Scope

SKILL.md keeps scope focused on reading/writing calendar.md and using the CLI for mutating actions. It also instructs the agent to write a rolling snapshot (default ./agent-snapshot.md) and documents optional Google OAuth env vars. This is expected for an agent-first calendar, but the snapshot and session persistence are effectively data-export operations worth noticing.

Install Mechanism

No install spec is declared (instruction-only from platform perspective), but the package contains normal Node.js code and a package.json with common deps (express, dotenv, fullcalendar, etc.). There are no download-from-URL installs or unusual third-party installers in the repo metadata.

Credentials

Requested environment variables (Google OAuth client id/secret/redirect URI, APP_BASE_URL, PORT, and snapshot config) are proportional to optional Google sync and running the local server. They are optional in package.json. Be aware that supplying GOOGLE_CLIENT_SECRET enables the app to obtain OAuth tokens which the server persists locally.

Persistence & Privilege

The server and CLI persist multiple files to the project root: agent snapshots (agent-snapshot.md by default or as configured by CALENDAR_AGENT_SNAPSHOT), .calendar-google-sync-state.json, and a session store (.calendar-sessions.json). Persisting OAuth tokens and calendar snapshots on disk is expected for this functionality but increases local data exposure and requires filesystem protection.

Assessment

This package is internally consistent with its description, but review and handle sensitive artifacts carefully before installing or running it: 1) Protect Google OAuth credentials (GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET) and only set them if you intend to enable Google sync. 2) The app will persist session tokens and sync mappings to .calendar-sessions.json and .calendar-google-sync-state.json in the project root — these files contain tokens/IDs that should be kept private; consider adding them to .gitignore or removing any seed files shipped in the repo. 3) The agent snapshot (agent-snapshot.md by default) will contain recent and upcoming events and can be pointed to any path via CALENDAR_AGENT_SNAPSHOT — do not set this to a location where sensitive data should not be written. 4) The repo includes dev scripts (Playwright screenshots, etc.) and a full Node app; run npm install only from a trusted environment and inspect the code if you have strict security requirements. 5) If you don't need Google sync, leave OAuth env vars unset to avoid creating persisted tokens. If you want more assurance, ask the author for provenance (homepage/source URL verification) or run the code in an isolated environment first.

Calendar Markdown + Google Sync Skill

Use this skill to query/update the local markdown-backed calendar safely and sync it with Google Calendar.

Source of Truth

• File: calendar.md
• Authoritative section: ## Event Records (fenced event YAML blocks)
• Human summary section: ## Event Checklist

Event Identity Rules

• id: local identifier
• externalId: stable cross-system identifier used for dedupe
• googleEventIds: per-calendar Google event mapping
• updatedAt: event-level timestamp for conflict resolution

Do not remove externalId from existing records.

Preferred Interface

Use CLI from repo root:

npm run cli -- <command>

Safe Query Flow

1. Run npm run cli -- summary.
2. If raw markdown is needed, run npm run cli -- export.

Safe Update Flow

1. Add (preferred for new events): npm run cli -- add --title "..." --start "<ISO>" --end "<ISO>" --category <id> [--shift-to-next|--allow-overlap]
2. Update: npm run cli -- update --id <event_id> [fields...] If changing --start or --end, include --shift-to-next or --allow-overlap in non-interactive runs.
3. Check/uncheck: npm run cli -- check --id <event_id> or --undone
4. Delete: npm run cli -- delete --id <event_id>
5. Add category: npm run cli -- category-add --id <id> --label "Label" --color "#9ca3af" --description "..."
6. Remove category: npm run cli -- category-remove --id <id> --reassign <id>

Conflict handling:

• add and time-changing update detect overlaps with existing events.
• Interactive runs can choose accept overlap, shift to next available slot, or provide a custom time.
• Non-interactive runs:
• --shift-to-next to auto-resolve to the next open window.
• --allow-overlap to keep the requested overlapping time.

Agent snapshot output:

• Every mutating CLI command writes a rolling markdown snapshot.
• Default path: ./agent-snapshot.md
• Override with CALENDAR_AGENT_SNAPSHOT.
• Recent window defaults to 14 days and is configurable with CALENDAR_AGENT_DAYS.
• Snapshot also includes upcoming 7 days when events exist.

UI Constraints

• UI does not provide add-event form/button.
• Events are created via CLI agents only.
• UI still supports drag/drop, resize, and check-off.

Google Sync Flow

1. In UI, sign in with Google.
2. Select target calendar via calendar selector controls.
3. Click Sync Now for two-way merge.

Sync state file:

• .calendar-google-sync-state.json

Import/Export

• Export: npm run cli -- export --out backup-calendar.md
• Import: npm run cli -- import --in backup-calendar.md

Notes for Agents

• Keep datetimes in ISO format.
• Prefer CLI operations over manual markdown edits.
• If categories are changed manually in frontmatter, keep id, label, and color fields valid.

Environment Variables

This skill uses the following environment variables (defined in .env):

• Google Calendar Sync (Optional)

  • GOOGLE_CLIENT_ID: Google OAuth Client ID
  • GOOGLE_CLIENT_SECRET: Google OAuth Client Secret
  • GOOGLE_REDIRECT_URI: Should be http://localhost:<PORT>/api/google/auth/callback

• Agent Configuration (Optional)

  • CALENDAR_AGENT_SNAPSHOT: Custom absolute or relative path to write the Markdown snapshot. Defaults to ./agent-snapshot.md.
  • CALENDAR_AGENT_DAYS: Number of historical days to include in the snapshot (defaults to 14).
  • PORT: API server port (defaults to 8787).
  • APP_BASE_URL: Base URL for the frontend UI.