claude_code_gmail_plugin: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Claude Code plugin for Gmail email analysis. Extends Gmail MCP with 5-category classification, auto-tagging, search, and label management. Also includes standalone CLI (main.py) using Claude Agent SDK.

Two modes of operation:

• Plugin (skills) — works inside Claude Code session via Gmail MCP tools + helper scripts
• Standalone CLI (main.py) — runs outside Claude Code via Claude Agent SDK (cannot run inside Claude Code due to nested session restriction)

Plugin Architecture

.claude-plugin/plugin.json     # plugin manifest ("gmail-analyzer")
skills/
  analyze-emails/SKILL.md      # 5-category email classification
  search-emails/SKILL.md       # Gmail query search
  manage-labels/SKILL.md       # label CRUD
  auto-tag/SKILL.md            # analyze + apply labels with confirmation
scripts/
  modify_labels.py             # apply label changes (stdin JSON)
  create_label.py              # create label (CLI arg)
  delete_label.py              # delete label (CLI arg)
  top_senders.py               # sender analytics (CLI args)

Skills ↔ MCP ↔ Scripts

Skills use Gmail MCP tools for read operations:

• gmail_search_messages, gmail_read_message, gmail_list_labels

Skills use scripts (via Bash) for write operations not available in MCP:

• modify_labels.py — add/remove labels from messages
• create_label.py / delete_label.py — label CRUD

Scripts communicate via JSON (stdin/stdout) and import gmail_client.py via sys.path.

Email categories

• 🟢 Personal / Личное
• 🔵 Useful Newsletter / Полезная рассылка
• 🟡 Important Notification / Важное уведомление
• 🟠 Noise / Шум
• 🔴 Spam / Мусор

Tagging JSON format

{"actions": [{"message_id": "...", "add": ["Label_ID"], "remove": ["Label_ID"]}]}

gmail_client.py

Gmail API client with three backends (auto-selected): gcloud ADC → gws CLI → credentials.json.