Efficient GWS Handler

Streamlined Google Workspace operations handler that routes commands to the correct GWS service automatically.

When to Use This Command

Run this command when you need to:

• Execute Google Workspace operations without remembering which specific GWS service to target
• Run multi-service workflows that span Gmail, Drive, Calendar, and other Workspace tools
• Perform batch operations across multiple GWS services in a single command invocation

Consider alternatives when:

• You know exactly which GWS service you need and want to call it directly for faster execution
• You need fine-grained control over service-specific parameters that the handler abstracts away

Quick Start

Configuration

Copy
name: efficient-gws-handler
type: command
category: google-workspace

Example Invocation

Copy
claude command:run efficient-gws-handler --task "find large files in Drive over 100MB"

Example Output

Routing to: Google Workspace Drive
  Operation: files.list
  Filter: size > 104857600

Results: 12 files found over 100MB
  presentations/Q4-Review.pptx     245 MB
  videos/product-demo.mp4          189 MB
  datasets/analytics-export.csv    156 MB
  ...9 more files

Total storage used by large files: 1.82 GB
Recommendation: Archive or delete unused files to free quota.

Core Concepts

Service Routing Overview

Aspect	Details
Services	Gmail, Drive, Calendar, Chat, Docs, Sheets, Keep, Admin, Groups
Routing	Natural language task descriptions mapped to appropriate GWS API calls
Batching	Multiple operations combined into a single authenticated session
Output	Unified format regardless of which underlying service handles the request
Fallback	Prompts for clarification when task intent maps to multiple services

Handler Workflow

Parse Task Description
        |
        v
Identify Target Service(s)
  |     |     |     |
  v     v     v     v
Gmail Drive  Cal  Chat
  |     |     |     |
  v     v     v     v
Execute Operations
        |
        v
Merge Results
        |
        v
Format Unified Output

Configuration

Parameter	Type	Default	Description
task	string	(required)	Natural language description of the operation to perform
services	string[]	auto	Restrict to specific services: gmail, drive, calendar, chat
dry-run	boolean	false	Show planned operations without executing them
output	string	table	Output format: table, json, csv for structured results
max-results	integer	100	Maximum number of results to return per service

Best Practices

1. Be specific in task descriptions - The routing engine performs better with concrete requests like "find unread emails from last week with attachments" than vague ones like "check my email."

2. Use dry-run for complex operations - Before executing batch modifications like deleting files or archiving emails, use dry-run to preview exactly which items will be affected.

3. Scope to specific services when possible - If you know the operation involves only Drive, restrict the services parameter to avoid unnecessary API calls to other services.

4. Review permissions before first use - The handler needs OAuth2 scopes for each service it accesses. Run gws auth status to verify all required scopes are authorized.

5. Combine related operations - Instead of running three separate commands for Gmail, Drive, and Calendar, describe the full workflow in one task to benefit from shared authentication.

Common Issues

1. Task routed to wrong service - Ambiguous descriptions like "check my schedule" might route to Calendar or Gmail. Add context like "check my Google Calendar events" for accurate routing.

2. Insufficient permissions for target service - The handler may route to a service you have not authorized. Run gws auth login --scopes drive,gmail to add missing scopes.

3. Timeout on large batch operations - Operations spanning thousands of items may exceed the default timeout. Use the max-results parameter to limit scope or break into smaller tasks.