Gmail AI Agent

AI email sorting and automated replies, straight from Gmail into your calendar and dashboard.

Automatically classify incoming emails with Google Gemini, schedule meeting events into Google Calendar, and review everything through a live React dashboard.

Stack · Features · Getting Started · Environment Variables · Project Structure · API · Built with AI

---

Stack

Backend

• Python 3.11+ · FastAPI · uvicorn
• Google Gemini API (google-genai) — email classification and summarization
• Gmail API + Google Calendar API (OAuth2)
• SQLite + SQLAlchemy — local history of processed emails
• pytest · httpx — testing

Frontend

• React 18 + TypeScript · Vite
• react-big-calendar + date-fns — interactive calendar
• Recharts — statistics charts (donut, bars, line)
• Axios — backend communication
• Vitest + React Testing Library + @vitest/coverage-v8 — component tests
• Centralized design system (src/theme.ts) — AI Futuristic Glow palette with dark theme, glassmorphism and animations
• Google Fonts: Space Grotesk (headings) · Inter (body) · IBM Plex Mono (AI outputs)
• Sonner — toast notifications (create/edit/delete events)

Deploy

• Docker + GitHub Actions (CI/CD)

---

Features

• Manual email processing: a "Process now" button on the dashboard
• AI classification: Gemini classifies each email with a category (meeting, urgent, promotion, informational, other) and generates a summary
• Manual meeting scheduling: emails classified as meeting show a "📅 Schedule" button that opens a pre-filled modal with the data extracted by Gemini (title, date, time, location, description). The user reviews and confirms before the event is created. If the email includes a .ics attachment, the data is extracted directly from the file with higher precision.
• Settings panel (/settings): adjust MAX_EMAILS_PER_RUN, CHECK_INTERVAL_MINUTES, GMAIL_FILTER_AFTER_DATE and the quiet hours (QUIET_HOURS_START/END) from the dashboard. Changes are persisted to .env and applied without restarting.
• Date filter: only processes emails received after GMAIL_FILTER_AFTER_DATE (default 2026/03/20)
• Configurable limit: up to 100 emails per run (MAX_EMAILS_PER_RUN)
• SQLite history: all processed emails are stored locally with category, summary and timestamp
• Daily briefing (/briefing): a narrative executive summary generated by Gemini. Structured cards with an overview, urgent emails (action required), meetings awaiting scheduling and agent recommendations. Supports querying the briefing for any past date.
• Smart history search: a free-text field using SQLite FTS5 (full-text search) to search simultaneously across subject, sender and summary. Combined with the existing date and category filters. Matched terms are highlighted in yellow in the results.
• Email dashboard with 3 tabs: To process · Processed today · Filterable + searchable history
• Statistics dashboard: donut by category · bars+line of daily volume · top senders
• Interactive calendar: two tabs (card list + month/week/day grid) · create · edit · delete events · inline actions on cards · color-coded labels
• Startup script: emaildgs starts backend + frontend and opens the browser automatically
• "AI Futuristic" UI: dark theme with #0B0F19 background, glassmorphism in the navbar, glow on AI buttons, an "AI thinking..." animation while processing, and react-big-calendar overrides for dark mode
• Professional hover effects: pulsing glow on primary buttons, lit border on secondary, red glow on danger
• Glassmorphism empty state: empty inbox with animated card instead of plain text
• Toast notifications: visual feedback when creating, editing and deleting calendar events
• Fix bug NaN: newly created calendar events already show the correct date (Google Calendar API response normalization)

---

Getting Started

Prerequisites

• Python 3.11+
• Node.js 18+
• Google Cloud credentials (Gmail API + Calendar API enabled)
• Google Gemini API Key

1. Clone the repository

git clone https://github.com/DeibyGS/gmail-ai-agent.git
cd gmail-ai-agent

2. Set up the backend

cd backend
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Copy the example file and fill in the variables:

cp .env.example .env
# Edit .env with your Gemini API key and Google OAuth2 configuration

3. Set up the frontend

cd frontend
npm install

4. Start the project

From the project root:

./emaildgs

This starts the backend (port 8000), the frontend (port 5173) and opens the browser automatically.

To stop: Ctrl+C

Manual start

# Terminal 1 — Backend
cd backend && source .venv/bin/activate && python main.py

# Terminal 2 — Frontend
cd frontend && npm run dev

Start with Docker

# Note: having backend/credentials.json and backend/.venv in place (OAuth2) is required
docker-compose up --build

Services available:

• Backend: http://localhost:8000
• Frontend: http://localhost:3000

Tests

# Backend
cd backend && source .venv/bin/activate && pytest

# Frontend
cd frontend && npm test              # watch mode
cd frontend && npm run test:coverage # with coverage report

---

Environment Variables

Copy backend/.env.example to backend/.env and fill in:

Variable	Description	Example
GEMINI_API_KEY	Google Gemini API Key	AIza...
GMAIL_FILTER_AFTER_DATE	Only process emails after this date	2026/03/20
MAX_EMAILS_PER_RUN	Maximum emails per run	100
CHECK_INTERVAL_MINUTES	Automatic scheduler interval	30
QUIET_HOURS_START	Quiet hours start (0–23)	0
QUIET_HOURS_END	Quiet hours end (0–24)	8

Google OAuth2 credentials are stored in backend/credentials.json and backend/token.json (not pushed to the repository).

---

Project Structure

gmail-ai-agent/
├── backend/
│   ├── config/settings.py          # Environment variables and credentials
│   ├── src/
│   │   ├── gmail/client.py         # Gmail API client
│   │   ├── ai/classifier.py        # Gemini classifier
│   │   ├── calendar/client.py      # Calendar API client
│   │   ├── scheduler/job.py        # Processing pipeline
│   │   ├── database/
│   │   │   ├── models.py           # SQLAlchemy models
│   │   │   ├── repository.py       # Data access
│   │   │   └── init_db.py          # SQLite initialization
│   │   └── api/
│   │       ├── routes.py           # Main endpoints
│   │       └── calendar_router.py  # Calendar endpoints
│   ├── tests/
│   ├── main.py
│   └── requirements.txt
├── frontend/
│   └── src/
│       ├── components/             # Navbar, EmailCard, modals
│       ├── pages/                  # EmailsPage · StatsPage · CalendarPage
│       ├── services/api.ts          # Backend API calls
│       └── types/index.ts           # TypeScript interfaces
├── docs/API.md                     # Full REST API reference
├── docker-compose.yml              # Backend + frontend orchestration
├── .github/workflows/ci.yml        # CI: pytest · ruff · vitest · docker build
├── emaildgs                        # Quick start script (local)
└── HANDOFF.md                      # Project state between sessions

---

API

See the full reference in docs/API.md.

Local base URL: http://localhost:8000

---

Built with AI

Built by a human developer working alongside AI agents (Claude Code + OpenCode) as pair-programming partners. The human hired the direction, reviewed every change, and made the architectural decisions; the AI generated the vast majority of the code under continuous human review.

Human-owned	AI-implemented (human-reviewed)
Requirements gathering, product scope, and SDD spec writing	LLM orchestration and Google Calendar integration
Architecture: project layout, router, single-model design	Users' email classification logic
Security decisions and authentication flow	Automated email categorization and labeling
Design system (colors, typography, CSS tokens)	Table components, filters, and calendar cards
Final UX copy and error-handling decisions	Form generation and backend webhook endpoints

No session metrics — the metrics have not yet been measured and are intentionally not invented.