# vishalbasker/gmail-triage-agent architecture

> Architecture diagram of the GitHub repository vishalbasker/gmail-triage-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vishalbasker/gmail-triage-agent
- Repository: https://github.com/vishalbasker/gmail-triage-agent

## Overview

This repository implements a Gmail draft-response workflow with three orchestration modes: a fixed fetch/triage workflow, instruction-driven thread matching and drafting, and personal calendar blocking. In live use, a Claude Code session mediates Gmail and Calendar MCP operations; Python clients receive data or queue proposed writes rather than making those calls themselves. The graph preserves independent meeting analysis, conflict checks, and the guarded hold-creation path. Some orchestrator and Calendar-agent source was excerpted only partially, so only documented or directly shown wiring is included.

Main entry points: [`orchestrator.py`](https://github.com/vishalbasker/gmail-triage-agent/blob/main/orchestrator.py) (Mode orchestrator), [`skills/logger.py`](https://github.com/vishalbasker/gmail-triage-agent/blob/main/skills/logger.py) (Decision logger), [`skills/llm_client.py`](https://github.com/vishalbasker/gmail-triage-agent/blob/main/skills/llm_client.py) (LLM client), [`agents/draft_agent.py`](https://github.com/vishalbasker/gmail-triage-agent/blob/main/agents/draft_agent.py) (Draft replies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow orchestration"]
  node_orchestrator["Mode orchestrator<br/>[orchestrator.py]"]
end

subgraph group_agents["Judgment agents"]
  node_fetch["Fetch and normalize<br/>[fetch_agent.py]"]
  node_triage["Reply triage<br/>[triage_agent.py]"]
  node_thread_match["Thread matching"]
  node_draft["Draft replies<br/>[draft_agent.py]"]
  node_calendar_agent["Meeting proposals<br/>[calendar_agent.py]"]
  node_scheduler["Block scheduling<br/>[scheduler_agent.py]"]
end

subgraph group_skills["Skills and clients"]
  node_llm_client["LLM client<br/>[llm_client.py]"]
  node_gmail_client["Gmail client<br/>[gmail_client.py]"]
  node_calendar_client["Calendar client<br/>[calendar_client.py]"]
  node_logger["Decision logger<br/>[logger.py]"]
  node_run_logs["Run logs"]
end

subgraph group_integrations["External systems"]
  node_gmail_mcp["Gmail MCP"]
  node_calendar_mcp["Calendar MCP"]
  node_claude_api["Claude API"]
end

node_user(("User"))
node_claude_session(("Claude Code session"))
node_manual_review(("Manual review"))

node_user -->|"supplies request"| node_orchestrator
node_orchestrator -->|"runs fetch"| node_fetch
node_fetch -->|"lists messages"| node_gmail_client
node_orchestrator -->|"runs fixed triage"| node_triage
node_orchestrator -->|"runs meeting analysis"| node_calendar_agent
node_orchestrator -->|"runs reply drafting"| node_draft
node_orchestrator -->|"runs instruction match"| node_thread_match
node_orchestrator -->|"runs block analysis"| node_scheduler
node_orchestrator -->|"creates hold"| node_calendar_client
node_triage -->|"requests judgment"| node_llm_client
node_thread_match -->|"requests match"| node_llm_client
node_draft -->|"requests reply text"| node_llm_client
node_calendar_agent -->|"requests meeting judgment"| node_llm_client
node_scheduler -->|"requests block extraction"| node_llm_client
node_draft -->|"creates draft"| node_gmail_client
node_draft -.->|"checks existing draft"| node_gmail_client
node_calendar_agent -->|"checks conflicts"| node_calendar_client
node_scheduler -->|"checks conflicts"| node_calendar_client
node_llm_client -.->|"calls when live"| node_claude_api
node_claude_session -.->|"calls live tools"| node_gmail_mcp
node_claude_session -.->|"calls live tools"| node_calendar_mcp
node_claude_session -.->|"feeds messages"| node_gmail_client
node_claude_session -.->|"feeds events"| node_calendar_client
node_gmail_client -.->|"provides pending drafts"| node_claude_session
node_calendar_client -.->|"provides pending holds"| node_claude_session
node_claude_session -.->|"creates live drafts"| node_gmail_mcp
node_claude_session -.->|"creates live hold"| node_calendar_mcp
node_calendar_agent -->|"surfaces proposals"| node_manual_review
node_orchestrator -->|"starts run log"| node_logger
node_fetch -->|"logs decision"| node_logger
node_triage -->|"logs decision"| node_logger
node_thread_match -->|"logs match"| node_logger
node_draft -->|"logs draft"| node_logger
node_calendar_agent -->|"logs proposal"| node_logger
node_scheduler -->|"logs decision"| node_logger
node_logger -->|"writes JSONL"| node_run_logs

click node_orchestrator "https://github.com/vishalbasker/gmail-triage-agent/blob/main/orchestrator.py"
click node_fetch "https://github.com/vishalbasker/gmail-triage-agent/blob/main/agents/fetch_agent.py"
click node_triage "https://github.com/vishalbasker/gmail-triage-agent/blob/main/agents/triage_agent.py"
click node_thread_match "https://github.com/vishalbasker/gmail-triage-agent/blob/main/agents/thread_match_agent.py"
click node_draft "https://github.com/vishalbasker/gmail-triage-agent/blob/main/agents/draft_agent.py"
click node_calendar_agent "https://github.com/vishalbasker/gmail-triage-agent/blob/main/agents/calendar_agent.py"
click node_scheduler "https://github.com/vishalbasker/gmail-triage-agent/blob/main/agents/scheduler_agent.py"
click node_llm_client "https://github.com/vishalbasker/gmail-triage-agent/blob/main/skills/llm_client.py"
click node_gmail_client "https://github.com/vishalbasker/gmail-triage-agent/blob/main/skills/gmail_client.py"
click node_calendar_client "https://github.com/vishalbasker/gmail-triage-agent/blob/main/skills/calendar_client.py"
click node_logger "https://github.com/vishalbasker/gmail-triage-agent/blob/main/skills/logger.py"
click node_run_logs "https://github.com/vishalbasker/gmail-triage-agent/tree/main/logs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_orchestrator,node_user,node_manual_review toneBlue
class node_fetch,node_triage,node_thread_match,node_draft,node_calendar_agent,node_scheduler toneAmber
class node_llm_client,node_gmail_client,node_calendar_client,node_logger,node_run_logs toneMint
class node_gmail_mcp,node_calendar_mcp,node_claude_api toneRose
class node_claude_session toneIndigo
```

## Components

### Workflow orchestration

- [Mode orchestrator](https://github.com/vishalbasker/gmail-triage-agent/blob/main/orchestrator.py): `orchestrator.py`

### Judgment agents

- [Fetch and normalize](https://github.com/vishalbasker/gmail-triage-agent/blob/main/agents/fetch_agent.py): `agents/fetch_agent.py`
- [Reply triage](https://github.com/vishalbasker/gmail-triage-agent/blob/main/agents/triage_agent.py): `agents/triage_agent.py`
- [Thread matching](https://github.com/vishalbasker/gmail-triage-agent/blob/main/agents/thread_match_agent.py): `agents/thread_match_agent.py`
- [Draft replies](https://github.com/vishalbasker/gmail-triage-agent/blob/main/agents/draft_agent.py): `agents/draft_agent.py`
- [Meeting proposals](https://github.com/vishalbasker/gmail-triage-agent/blob/main/agents/calendar_agent.py): `agents/calendar_agent.py`
- [Block scheduling](https://github.com/vishalbasker/gmail-triage-agent/blob/main/agents/scheduler_agent.py): `agents/scheduler_agent.py`

### Skills and clients

- [LLM client](https://github.com/vishalbasker/gmail-triage-agent/blob/main/skills/llm_client.py): `skills/llm_client.py`
- [Gmail client](https://github.com/vishalbasker/gmail-triage-agent/blob/main/skills/gmail_client.py): `skills/gmail_client.py`
- [Calendar client](https://github.com/vishalbasker/gmail-triage-agent/blob/main/skills/calendar_client.py): `skills/calendar_client.py`
- [Decision logger](https://github.com/vishalbasker/gmail-triage-agent/blob/main/skills/logger.py): `skills/logger.py`
- [Run logs](https://github.com/vishalbasker/gmail-triage-agent/tree/main/logs): `logs`

### External systems

- **Gmail MCP**
- **Calendar MCP**
- **Claude API**

### Other components

- **User**
- **Claude Code session**
- **Manual review**

## Connections

- User → Mode orchestrator: supplies request
- Mode orchestrator → Fetch and normalize: runs fetch
- Fetch and normalize → Gmail client: lists messages
- Mode orchestrator → Reply triage: runs fixed triage
- Mode orchestrator → Meeting proposals: runs meeting analysis
- Mode orchestrator → Draft replies: runs reply drafting
- Mode orchestrator → Thread matching: runs instruction match
- Mode orchestrator → Block scheduling: runs block analysis
- Mode orchestrator → Calendar client: creates hold
- Reply triage → LLM client: requests judgment
- Thread matching → LLM client: requests match
- Draft replies → LLM client: requests reply text
- Meeting proposals → LLM client: requests meeting judgment
- Block scheduling → LLM client: requests block extraction
- Draft replies → Gmail client: creates draft
- Draft replies → Gmail client: checks existing draft
- Meeting proposals → Calendar client: checks conflicts
- Block scheduling → Calendar client: checks conflicts
- LLM client → Claude API: calls when live
- Claude Code session → Gmail MCP: calls live tools
- Claude Code session → Calendar MCP: calls live tools
- Claude Code session → Gmail client: feeds messages
- Claude Code session → Calendar client: feeds events
- Gmail client → Claude Code session: provides pending drafts
- Calendar client → Claude Code session: provides pending holds
- Claude Code session → Gmail MCP: creates live drafts
- Claude Code session → Calendar MCP: creates live hold
- Meeting proposals → Manual review: surfaces proposals
- Mode orchestrator → Decision logger: starts run log
- Fetch and normalize → Decision logger: logs decision
- Reply triage → Decision logger: logs decision
- Thread matching → Decision logger: logs match
- Draft replies → Decision logger: logs draft
- Meeting proposals → Decision logger: logs proposal
- Block scheduling → Decision logger: logs decision
- Decision logger → Run logs: writes JSONL