Tools
Smart Calendar
By Smart calendar plugin for OpenClaw — travel buffers, bulk ops, conflict detection. Built on Gog.
Install
npm install -gREADME
# openclaw-smart-calendar
[](https://www.npmjs.com/package/openclaw-smart-calendar)
[](LICENSE)
Intelligent Google Calendar management for OpenClaw — travel buffers, conflict detection, AI scheduling suggestions, pattern detection, and daily briefings.
Built on top of **[Google Workspace CLI (gws)](https://github.com/googleworkspace/cli)** — structured JSON output, zero boilerplate.
---
## Table of Contents
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Google Calendar Setup](#google-calendar-setup)
- [Configuration](#configuration)
- [Usage](#usage)
- [Tools Reference](#tools-reference)
- [Smart Features](#smart-features)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
---
## Prerequisites
Before installing the plugin, you need:
1. **An OpenClaw instance** — running on your machine, server, or DigitalOcean droplet
2. **Node.js 18+** — required for the `gws` CLI
3. **A Google account** — with access to Google Calendar
4. **A Google Cloud project** — required for API access (free tier is sufficient)
### Setting up a Google Cloud project
If you don't already have a Google Cloud project, follow these steps:
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Click **Select a project** → **New Project**
3. Give it a name (e.g., "Smart Calendar") and click **Create**
4. Once created, make sure the project is selected in the top bar
### Enabling the Google Calendar API
1. Go to [Google Calendar API page](https://console.cloud.google.com/apis/library/calendar-json.googleapis.com)
2. Make sure your project is selected in the top bar
3. Click **Enable**
### Setting up OAuth consent screen
1. Go to [OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent)
2. Select **External** as user type → click **Create**
3. Fill in:
- App name: `Smart Calendar` (or any name)
- User support email: your email
- Developer contact email: your email
4. Click **Save and Continue** through all screens
5. Under **Test users**, click **Add users** → add your Google email
6. Click **Save**
### Creating OAuth credentials
1. Go to [Credentials page](https://console.cloud.google.com/apis/credentials)
2. Click **Create Credentials** → **OAuth client ID**
3. Application type: **Desktop app**
4. Name: `Smart Calendar` (or any name)
5. Click **Create**
6. **Download the JSON file** — you'll need this in the next step
---
## Installation
### Step 1: Install the plugin
```bash
openclaw plugins install openclaw-smart-calendar
```
This automatically installs the `gws` CLI if it's not already on your system.
### Step 2: Restart OpenClaw
```bash
systemctl restart openclaw
```
---
## Google Calendar Setup
Choose the setup method that fits your environment:
### Option A: Interactive setup (local machine with browser)
Best for: laptops, desktops — anywhere you have a web browser.
```bash
# 1. Place the downloaded OAuth JSON file
mkdir -p ~/.config/gws
cp ~/Downloads/client_secret_*.json ~/.config/gws/client_secret.json
# 2. Login (opens your browser)
gws auth login -s calendar
# 3. Approve access in the browser
# - If you see "Google hasn't verified this app", click "Continue"
# - Select all scopes / checkboxes and click "Continue"
# 4. Verify it works
gws calendar +agenda --today
```
### Option B: Exported OAuth (server / cloud deployment)
Best for: DigitalOcean droplets, VPS, headless servers — anywhere without a browser.
**On your local machine (has browser):**
```bash
# 1. Install gws locally
npm install -g @googleworkspace/cli
# 2. Place the OAuth JSON file
mkdir -p ~/.config/gws
cp ~/Downloads/client_secret_*.json ~/.config/gws/client_secret.json
# 3. Login locally (opens browser)
gws auth login -s calendar
# 4. Export credentials to a file
gws auth export --unmasked > ~/credentials.json
```
**Copy to your server:**
```bash
scp ~/credentials.json root@your-server-ip:/root/credentials.json
```
**On your server:**
```bash
# 1. Set the credentials path
echo 'export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/root/credentials.json' >> ~/.bashrc
source ~/.bashrc
# 2. Verify it works
gws calendar +agenda --today
```
### Option C: Service Account (advanced)
Best for: production servers, CI/CD, automated workflows.
1. Go to [Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts)
2. Click **Create Service Account** → give it a name → **Create**
3. Click on the service account → **Keys** → **Add Key** → **JSON** → **Create**
4. Save the downloaded JSON file to your server
```bash
# On your server:
echo 'export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json' >> ~/.bashrc
source ~/.bashrc
```
**Important:** Share your Google Calendar with the service account email address (found in the JSON file as `client_email`). Go to Google Calendar → Settings → Share with specific people → Add the service account email with "Make changes to events" permission.
### Using the setup wizard
Alternatively, run the interactive setup wizard which guides you through all options:
```bash
npx openclaw-smart-calendar setup
```
---
## Configuration
All settings have sensible defaults. Configure via OpenClaw UI or set in your OpenClaw config:
| Setting | Default | Description |
|---------|---------|-------------|
| `user_timezone` | `Asia/Kolkata` | Your IANA timezone (e.g., `America/New_York`, `Europe/London`) |
| `google_maps_api_key` | — | Google Maps API key for automatic travel time estimation |
| `home_address` | — | Your home address for travel time calculations |
| `office_address` | — | Your office address for travel time calculations |
| `default_travel_buffer_minutes` | `30` | Fallback travel buffer when Maps API is unavailable |
| `online_buffer_minutes` | `5` | Buffer minutes before online meetings |
| `audit_log_path` | `~/.openclaw/smart-cal-audit.log` | Path to the audit log file |
---
## Usage
Just talk to your OpenClaw agent (Telegram, CLI, etc.):
### Querying your calendar
| Say this | What happens |
|----------|-------------|
| "What's on my calendar today?" | Lists today's events |
| "What's on my calendar tomorrow?" | Lists tomorrow's events |
| "Show my afternoon meetings" | Lists events for a specific period |
| "What does my week look like?" | Weekly summary with breakdown |
### Adding events
| Say this | What happens |
|----------|-------------|
| "Add dentist at 123 Main St tomorrow at 2pm" | Creates event + auto travel buffer |
| "Add lunch with Raj tomorrow at 1pm at Indiranagar" | Creates event with location-aware buffer |
| "Add standup at 9am" | Creates a simple event |
### Managing events
| Say this | What happens |
|----------|-------------|
| "Clear tomorrow morning" | Deletes all morning events |
| "Block 10am-12pm Friday for deep work" | Creates a time block |
| "Move my 2pm meeting to 4pm" | Reschedules the event |
### Smart features
| Say this | What happens |
|----------|-------------|
| "Morning briefing" or "What's my day look like?" | Full daily briefing with schedule, free time, and warnings |
| "Brief me on tomorrow" | Daily briefing for a specific day |
| "Find recurring patterns" or "What meetings repeat?" | Detects patterns and suggests recurring events |
---
## Tools Reference
| Tool | Description |
|------|-------------|
| `smart_cal_add` | Add event with travel buffer and conflict detection. Suggests alternative slots when conflicts are found. |
| `smart_cal_query` | List events for a date or time range |
| `smart_cal_clear` | Delete all events in a time range |
| `smart_cal_block` | Block a time slot on the calendar |
| `smart_cal_reschedule` | Move an event to a new time |
| `smart_cal_status` | Weekly summary with in-person vs online breakdown |
| `smart_cal_briefing` | Daily briefing with schedule, free time, leave-by times, and warnings |
| `smart_cal_patterns` | Detect recurring meeting patterns and suggest making them formal |
---
## Smart Features
### AI-Powered Scheduling
When you add an event that conflicts with existing ones, the plugin analyzes your past 4 weeks of calendar data and suggests optimal alternative time slots based on:
- Historically quiet hours (when you're usually free)
- Meeting type (in-person meetings prefer low-traffic hours)
- Buffer gaps between meetings
- Time-of-day preferences
### Travel Buffer Intelligence
- **In-person meetings** (physical address detected) → automatic travel buffer added before the event
- **Online meetings** (Zoom/Meet/Teams URL detected) → no travel buffer needed
- With a Google Maps API key configured, travel time is calculated based on actual driving distance
### Pattern Detection
Scans your calendar history (default: 8 weeks) to find meetings that repeat without being formally set as recurring. It detects:
- Daily, weekly, biweekly, and monthly patterns
- Confidence scoring (only suggests patterns with 3+ occurrences)
- Predicted next occurrence
### Daily Briefing
A comprehensive morning summary including:
- Total events with in-person vs online breakdown
- First meeting time with leave-by time for in-person events
- Complete schedule listing
- Free time blocks during working hours (8am–8pm)
- Warnings for: back-to-back meetings, short gaps between in-person meetings at different locations, missing locations, and overloaded days
### Conflict Detection
Automatically checks for scheduling overlaps when creating events and warns you with details about the conflicting meetings.
### Audit Log
Every calendar change (create, delete, reschedule) is logged to `~/.openclaw/smart-cal-audit.log` for your records.
---
## Troubleshooting
### "gws command failed" errors
- Make sure `gws` is installed: `gws --version`
- If not installed: `npm install -g @googleworkspace/cli`
- Check auth: `gws calendar +agenda --today`
###
... (truncated)
tools
Comments
Sign in to leave a comment