Integrations: OAuth, Gmail, Calendar

Integrations: OAuth, Gmail, Calendar

PocketPaw integrates with Google services via OAuth 2.0. Currently supported: Gmail and Google Calendar.

OAuth Framework

Setup

1. Create a Google Cloud project at console.cloud.google.com
2. Enable the Gmail API and Google Calendar API
3. Create OAuth 2.0 credentials (Desktop app type)
4. Add your client ID and secret to PocketPaw config

{
  "google_oauth_client_id": "your-client-id.apps.googleusercontent.com",
  "google_oauth_client_secret": "your-client-secret"
}

Auth Flow

1. Agent (or user) triggers an action requiring Google access
2. PocketPaw generates an authorization URL
3. User visits the URL, grants permission, receives an auth code
4. Dashboard provides endpoints for this flow:
   • GET /api/oauth/authorize — Returns the authorization URL
   • GET /oauth/callback — Handles the redirect with auth code
5. Tokens are stored securely at ~/.pocketclaw/oauth/

Token Storage

• Tokens saved as JSON files (one per service, e.g., google_gmail.json)
• Files are chmod 0600 (owner-only read/write)
• Automatic token refresh when expired (60-second buffer before expiry)
• TokenStore methods: save(), load(), delete(), list_services()

Configuration

Gmail

Three core tools for email management, plus helper tools for labels and batch operations.

Tools

Additional Tools

Query Syntax

Gmail search supports the standard Gmail query operators:

"from:alice@example.com"          # From specific sender
"subject:meeting"                  # Subject contains "meeting"
"is:unread after:2026/01/01"      # Unread since Jan 2026
"has:attachment filename:pdf"      # PDFs with attachments
"label:work -label:archived"       # In "work" label, not archived

Example

You: "Search my Gmail for unread emails from my manager"
Me:  *calls search_gmail with "is:unread from:manager@company.com"*
Me:  "Found 3 unread emails. The most recent is about the Q1 planning doc..."

Tool Policy Group

Gmail tools belong to group:gmail. To restrict:

{
  "tools_deny": ["group:gmail"]
}

Calendar

Three tools for calendar management.

Tools

Example

You: "What meetings do I have today?"
Me:  *calls calendar_list with days_ahead=1*
Me:  "You have 3 meetings: standup at 9am, design review at 11am, 1-on-1 at 3pm."

You: "Schedule a 30-min sync with Alice tomorrow at 2pm"
Me:  *calls calendar_create*
Me:  "Created! '30-min sync' on Feb 8 at 2:00 PM with alice@company.com."

Tool Policy Group

Calendar tools belong to group:calendar. To restrict:

{
  "tools_deny": ["group:calendar"]
}

Implementation

Tests

• tests/test_oauth.py — OAuth framework tests
• tests/test_gmail.py — Gmail integration tests
• tests/test_gcalendar.py — Calendar integration tests