Initial commit

commands/gcal.md

@@ -0,0 +1,123 @@
+---
+description: Guide for using the gcallm CLI to add events to Google Calendar with natural language
+---
+
+# Google Calendar CLI Usage Guide
+
+Use the `gcallm` CLI to add events to Google Calendar using natural language.
+
+## Quick Reference
+
+### Add Events
+```bash
+# Direct text input
+gcallm "Meeting with Sarah tomorrow at 3pm"
+gcallm "Lunch next Tuesday 12-1pm at Cafe Nero"
+gcallm add "Team standup Mon-Fri 9:30am"
+
+# Multiple events at once
+gcallm "Team standup Mon-Fri 9:30am, Coffee with Alex Thursday 2pm"
+```
+
+### From Files (Preferred for Automation)
+```bash
+# Pipe from file
+cat /tmp/gcal/events.txt | gcallm
+cat schedule.txt | gcallm
+
+# Echo to stdin
+echo "Doctor appointment Friday 10am" | gcallm
+```
+
+### From Clipboard
+```bash
+# Uses clipboard if no stdin/args provided
+gcallm
+```
+
+### From Screenshots
+```bash
+# Parse latest screenshot on Desktop
+gcallm -s "Add events from this screenshot"
+
+# Parse multiple screenshots
+gcallm --screenshots 2 "Add from last 2 screenshots"
+```
+
+### Ask Questions
+```bash
+# General calendar questions
+gcallm ask "What's on my calendar today?"
+gcallm ask "When is my next meeting?"
+gcallm ask "Am I free Thursday afternoon?"
+```
+
+### List Calendars
+```bash
+gcallm calendars
+```
+
+## Common Workflow
+
+**Recommended approach for scripts:**
+```bash
+# 1. Write event details to a temp file
+cat > /tmp/gcal/events.txt << 'EOF'
+Meeting with Prof. Smith Monday 2pm
+Coffee with Alex Tuesday 10am
+Team standup Wed-Fri 9:30am
+EOF
+
+# 2. Pipe to gcallm
+cat /tmp/gcal/events.txt | gcallm
+```
+
+## Natural Language Examples
+
+gcallm understands flexible date/time formats:
+- "tomorrow at 3pm"
+- "next Tuesday 12-1pm"
+- "Monday through Friday at 9:30am"
+- "December 15th 2pm for 2 hours"
+- "Coffee with Alex 10am at Starbucks"
+- "Team meeting every Monday 9am"
+
+## Configuration
+
+```bash
+# Configure model (default: claude-sonnet-4-20250514)
+gcallm config --model claude-sonnet-4-20250514
+
+# Configure custom prompt
+gcallm config --prompt "Custom extraction prompt"
+
+# Show current config
+gcallm config --show
+```
+
+Config stored at: `~/.config/gcallm/config.json`
+
+## Verification
+
+```bash
+# Verify setup
+gcallm verify
+```
+
+## Troubleshooting
+
+### "MCP server not configured" Error
+Ensure the Google Calendar MCP is configured in Claude Code:
+```bash
+claude mcp add gcal npx @anthropic/mcp-google-calendar -s local
+```
+
+### OAuth Issues
+Re-run setup:
+```bash
+gcallm setup ~/path/to/oauth-keys.json
+```
+
+## Related Commands
+
+- `/gcal:setup` - Set up gcallm with OAuth credentials

commands/setup.md

@@ -0,0 +1,132 @@
+---
+description: Set up gcallm CLI with Google Calendar OAuth2 credentials
+---
+
+# Google Calendar CLI Setup
+
+This command guides you through setting up the `gcallm` CLI for adding events to Google Calendar.
+
+## Prerequisites
+
+You need:
+1. OAuth2 credentials from Google Cloud Console
+2. Google Calendar MCP server configured in Claude Code
+
+## Step 1: Get OAuth2 Credentials
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
+2. Create a new project or select an existing one
+3. Enable the **Google Calendar API**:
+   - Go to "APIs & Services" > "Enable APIs and Services"
+   - Search for "Google Calendar API" and enable it
+4. Create OAuth2 credentials:
+   - Go to "Credentials" > "Create Credentials" > "OAuth client ID"
+   - Application type: **Desktop app**
+   - Name: "Calendar CLI" (or any name)
+   - Click "Create"
+5. Download the credentials JSON file
+6. Save it somewhere accessible (e.g., `~/gcp-oauth.keys.json`)
+
+## Step 2: Install gcallm
+
+```bash
+# Install from PyPI
+uv tool install gcallm
+
+# Or with pip
+pip install gcallm
+```
+
+Verify installation:
+```bash
+which gcallm
+# Should output: /Users/wz/.local/bin/gcallm
+```
+
+## Step 3: Configure OAuth Path
+
+Point gcallm to your OAuth credentials:
+```bash
+gcallm setup ~/gcp-oauth.keys.json
+```
+
+Or interactively:
+```bash
+gcallm setup
+# Will prompt for path
+```
+
+## Step 4: Configure Google Calendar MCP
+
+gcallm requires the Google Calendar MCP server. Add it to Claude Code:
+
+```bash
+claude mcp add gcal npx @anthropic/mcp-google-calendar -s local
+```
+
+This uses the OAuth credentials you configured.
+
+## Step 5: Verify Setup
+
+```bash
+gcallm verify
+```
+
+Expected output:
+```
+Google Calendar MCP: OK
+OAuth credentials: Configured
+```
+
+Test with a simple query:
+```bash
+gcallm ask "What's on my calendar today?"
+```
+
+## Configuration Files
+
+```
+~/.config/gcallm/
+├── config.json         # Settings (model, prompt)
+└── oauth_path          # Path to OAuth credentials
+
+# OAuth credentials (shared with other Google tools)
+~/gcp-oauth.keys.json   # Or wherever you saved it
+```
+
+## Troubleshooting
+
+### "MCP server not configured" Error
+
+The Google Calendar MCP server isn't set up:
+```bash
+# Add the MCP server
+claude mcp add gcal npx @anthropic/mcp-google-calendar -s local
+
+# Verify it's configured
+claude mcp list
+```
+
+### "OAuth credentials not found" Error
+
+Re-run setup with the correct path:
+```bash
+gcallm setup /correct/path/to/oauth-keys.json
+```
+
+### Authentication Failed
+
+Your OAuth token may have expired. Re-authenticate:
+1. Delete existing credentials: `rm ~/.config/gcallm/*`
+2. Re-run: `gcallm setup ~/gcp-oauth.keys.json`
+3. Complete the browser authentication flow
+
+### Permission Denied
+
+Ensure the OAuth app has calendar scope:
+1. Go to Google Cloud Console > APIs & Services > OAuth consent screen
+2. Add scope: `https://www.googleapis.com/auth/calendar`
+
+## Related Commands
+
+- `/gcal` - Usage guide for gcallm CLI