# anthropics/claude-agent-sdk-demos architecture

> Architecture diagram of the GitHub repository anthropics/claude-agent-sdk-demos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anthropics/claude-agent-sdk-demos
- Repository: https://github.com/anthropics/claude-agent-sdk-demos

## Overview

1. **What this repo is**
   - This is a **monorepo of independent Claude Agent SDK demos**, not one unified product.
   - Each demo folder has its own runtime, UI, and integration style; they do not appear to share a common application layer beyond the SDK usage patterns and documentation.

2. **Common architecture pattern across demos**
   - Most demos sit on the same boundary: a **human-facing shell** (CLI, React web app, or Electron app) talks to a **Claude-powered orchestration layer**, which may then call tools, hit external services, or read/write local state.
   - The important architectural distinction is usually between:
     - **presentation layer**: browser/desktop/terminal UI
     - **agent/orchestration layer**: SDK session, prompts, tool routing, subagent coordination
     - **integration layer**: email, filesystem, web search, document generation, database, or IMAP
     - **state layer**: local session store, SQLite/db files, logs, or generated artifacts

3. **Email Agent: the largest, most layered demo**
   - `email-agent` is the most complete system in the repo and is built as a **local email assistant**.
   - It has four major parts:
     - `client/`: React UI for inbox, email viewer, listeners panel, actions, and chat-style assistance
     - `server/`: HTTP/WebSocket endpoints for emails, sync, listeners, and UI state
     - `database/`: email persistence, search, sync, IMAP integration, and schema/migrations
     - `ccsdk/`: orchestration code for actions, listeners, UI-state management, message queueing, and websocket handling
   - The `agent/custom_scripts/` tree contains the user-extensible business logic for **actions**, **listeners**, and **UI states**.

4. **Email Agent data flow**
   - Email enters through **IMAP sync** into the database layer.
   - The UI reads inbox/search results and listener status from the server endpoints.
   - Agent-driven behaviors run through the `ccsdk` managers: listeners react to email events, actions execute workflows, and UI-state components feed the frontend.
   - WebSocket connectivity is used for live assistant interaction and state updates, so the UI is not just polling static data; it is reacting to ongoing agent activity.
   - The main external dependencies are the **email server via IMAP** and **Anthropic/Claude** for reasoning and tool use.

5. **Email Agent’s extensibility model**
   - The repo treats actions, listeners, and UI states as first-class plugins.
   - `agent/custom_scripts/actions/` and `listeners/` define concrete automation behaviors, while `ui-states/` provides domain-specific dashboards.
   - The `agent/.claude/skills/` and template files show that this project is designed for **generating new automations from a pattern**, not just hardcoding one assistant.
   - That makes the architecture more of a **framework for email automations** than a single-purpose app.

6. **AskUserQuestion Previews: browser-mediated tool interaction**
   - `ask-user-question-previews` is a smaller web demo focused on one SDK capability: **AskUserQuestion** with **HTML preview cards**.
   - It has a simple split between `client/` and `server.ts`, with `useAgentSocket.ts` mediating the real-time bridge.
   - The key flow is: Claude requests a clarification question → the browser renders preview options as styled HTML → the selected answer is sent back over WebSocket to continue the agent run.
   - Architecturally, this demo highlights the **tool-callback-to-UI roundtrip**, not persistent storage or backend business logic.

7. **Simple Chat App: minimal full conversation loop**
   - `simple-chatapp` is a compact React + server implementation of a chat experience backed by the SDK.
   - `client/` provides the chat window and chat list UI, while `server/` contains the AI client, session management, and chat store.
   - The important boundary here is the **streaming chat session**: user messages go from the browser to the server, the server streams model responses, and session state is preserved centrally.
   - This demo is useful as the repo’s cleanest example of the **end-to-end conversational loop**.

8. **Excel Demo: desktop app with Electron boundaries**
   - `excel-demo` is structurally different because it is an **Electron application**.
   - It has the standard Electron split:
     - `src/main/`: main process, menu, and preload wiring
     - `src/renderer/`: React UI and chat/tool display components
     - `src/main/preload.ts`: bridge between renderer and privileged main-process APIs
   - The presence of `agent/.claude/skills/xlsx/` and a Python `recalc.py` script suggests the agent can operate on spreadsheets through a **tooling layer outside the UI**, rather than directly in the renderer.
   - The architecture centers on a **desktop shell + local file/tool operations + AI assistance** pattern.

9. **Research Agent: multi-agent orchestration**
   - `research-agent` is a Python-based workflow for **delegating research across specialized subagents**.
   - The core package contains:
     - `agent.py` as the main coordinator
     - prompts for `lead_agent`, `researcher`, `data_analyst`, and `report_writer`
     - utilities for transcript capture, message handling, and subagent tracking
   - The data flow is: user topic → lead agent decomposes the task → parallel research agents gather findings → synthesis/report-writing agents produce a final report.
   - This repo emphasizes **coordination, parallelism, and traceability of subagent work** more than UI concerns.

10. **Resume Generator: document-production pipeline**
   - `resume-generator` is a smaller, likely CLI-oriented demo focused on creating a **one-page .docx resume** from a person’s name.
   - Its architecture is a pipeline from input name → web research (LinkedIn/GitHub/news) → content assembly → document generation.
   - The `docx` Claude skill directory indicates the last stage is a **formatted document output**, not a persistent service or interactive UI.

11. **Hello World and Hello World V2**
   - These are the smallest examples in the repo and serve as **SDK onboarding/reference points**.
   - `hello-world` is a minimal single-file TypeScript example.
   - `hello-world-v2` demonstrates the newer session-oriented API patterns, especially separate send/stream behavior and multi-turn state handling.
   - They define the baseline mental model used by the larger demos, but they are not the architectural center of the repo.

12. **How to read the repo as a system**
   - Think of the repository as a set of **reference architectures for Claude Agent SDK integration**:
     - browser chat apps
     - email automation
     - desktop file automation
     - multi-agent research
     - document generation
   - The main architectural decisions vary by demo, but the recurring pattern is the same: **UI or CLI input → agent orchestration → external tool/service integration → returned UI/state/output**.

Main entry points: [`email-agent/ccsdk/session.ts`](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/email-agent/ccsdk/session.ts) (CCSDK core), [`research-agent/research_agent/agent.py`](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/research-agent/research_agent/agent.py) (Lead agent), [`simple-chatapp/server/server.ts`](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/simple-chatapp/server/server.ts) (Chat backend), [`email-agent/server/server.ts`](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/email-agent/server/server.ts) (API server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shared["Shared demos"]
  node_hello1["Hello World<br/>starter demo<br/>[hello-world.ts]"]
  node_hello2["Hello World v2<br/>session demo<br/>[v2-examples.ts]"]
end

subgraph group_ask["AskUserQuestion"]
  node_ask_ui["Browser UI<br/>react client<br/>[App.tsx]"]
  node_ask_socket["Socket bridge<br/>ws hook<br/>[useAgentSocket.ts]"]
  node_ask_server["Demo server<br/>node server<br/>[server.ts]"]
end

subgraph group_simple["Simple chat"]
  node_chat_ui["Chat UI<br/>react client<br/>[App.tsx]"]
  node_chat_server["Chat backend<br/>node server<br/>[server.ts]"]
  node_chat_store[("Chat store<br/>state store<br/>[chat-store.ts]")]
end

subgraph group_email["Email agent"]
  node_email_ui["Email UI<br/>react client<br/>[App.tsx]"]
  node_email_server["API server<br/>http/ws server<br/>[server.ts]"]
  node_email_ccsdk{{"CCSDK core<br/>orchestration layer<br/>[session.ts]"}}
  node_email_actions["Actions<br/>automation plugins"]
  node_email_listeners["Listeners<br/>event plugins"]
  node_email_ui_states["UI states<br/>dashboard plugins"]
  node_email_db[("Email DB<br/>persistence layer<br/>[email-db.ts]")]
  node_email_imap["IMAP sync<br/>mail integration<br/>[imap-manager.ts]"]
end

subgraph group_excel["Excel demo"]
  node_excel_main["Main process<br/>electron main<br/>[main.ts]"]
  node_excel_preload["Preload bridge<br/>electron bridge<br/>[preload.ts]"]
  node_excel_renderer["Renderer UI<br/>react desktop UI<br/>[App.tsx]"]
  node_excel_xlsx["XLSX skill<br/>spreadsheet tool<br/>[SKILL.md]"]
end

subgraph group_research["Research agent"]
  node_research_agent{{"Lead agent<br/>workflow coordinator<br/>[agent.py]"}}
  node_research_prompts["Agent prompts<br/>prompt set<br/>[lead_agent.txt]"]
  node_research_utils["Trace utils<br/>tracking utilities"]
end

subgraph group_resume["Resume generator"]
  node_resume_pipe["Resume pipeline<br/>doc generator"]
  node_resume_docx["DOCX skill<br/>document tool<br/>[SKILL.md]"]
end

node_sdk{{"Claude SDK<br/>agent runtime"}}

node_hello1 -->|"uses"| node_sdk
node_hello2 -->|"uses"| node_sdk
node_ask_ui -->|"events"| node_ask_socket
node_ask_socket -->|"ws"| node_ask_server
node_ask_server -->|"uses"| node_sdk
node_chat_ui -->|"http/stream"| node_chat_server
node_chat_server -->|"persists"| node_chat_store
node_chat_server -->|"uses"| node_sdk
node_email_ui -->|"api/ws"| node_email_server
node_email_server -->|"delegates"| node_email_ccsdk
node_email_ccsdk -->|"uses"| node_sdk
node_email_ccsdk -->|"runs"| node_email_actions
node_email_ccsdk -->|"reacts"| node_email_listeners
node_email_ccsdk -->|"drives"| node_email_ui_states
node_email_server -->|"reads/writes"| node_email_db
node_email_db -->|"syncs"| node_email_imap
node_excel_main -->|"bridges"| node_excel_preload
node_excel_preload -->|"api"| node_excel_renderer
node_excel_renderer -->|"uses"| node_sdk
node_excel_main -->|"tools"| node_excel_xlsx
node_research_agent -->|"orchestrates"| node_research_prompts
node_research_agent -->|"tracks"| node_research_utils
node_research_agent -->|"uses"| node_sdk
node_resume_pipe -->|"formats"| node_resume_docx
node_resume_pipe -->|"uses"| node_sdk

click node_hello1 "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/hello-world/hello-world.ts"
click node_hello2 "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/hello-world-v2/v2-examples.ts"
click node_ask_ui "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/ask-user-question-previews/client/App.tsx"
click node_ask_socket "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/ask-user-question-previews/client/useAgentSocket.ts"
click node_ask_server "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/ask-user-question-previews/server.ts"
click node_chat_ui "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/simple-chatapp/client/App.tsx"
click node_chat_server "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/simple-chatapp/server/server.ts"
click node_chat_store "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/simple-chatapp/server/chat-store.ts"
click node_email_ui "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/email-agent/client/App.tsx"
click node_email_server "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/email-agent/server/server.ts"
click node_email_ccsdk "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/email-agent/ccsdk/session.ts"
click node_email_actions "https://github.com/anthropics/claude-agent-sdk-demos/tree/main/email-agent/agent/custom_scripts/actions"
click node_email_listeners "https://github.com/anthropics/claude-agent-sdk-demos/tree/main/email-agent/agent/custom_scripts/listeners"
click node_email_ui_states "https://github.com/anthropics/claude-agent-sdk-demos/tree/main/email-agent/agent/custom_scripts/ui-states"
click node_email_db "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/email-agent/database/email-db.ts"
click node_email_imap "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/email-agent/database/imap-manager.ts"
click node_excel_main "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/excel-demo/src/main/main.ts"
click node_excel_preload "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/excel-demo/src/main/preload.ts"
click node_excel_renderer "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/excel-demo/src/renderer/App.tsx"
click node_excel_xlsx "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/excel-demo/agent/.claude/skills/xlsx/SKILL.md"
click node_research_agent "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/research-agent/research_agent/agent.py"
click node_research_prompts "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/research-agent/research_agent/prompts/lead_agent.txt"
click node_research_utils "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/research-agent/research_agent/utils/subagent_tracker.py"
click node_resume_pipe "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/resume-generator/resume-generator.ts"
click node_resume_docx "https://github.com/anthropics/claude-agent-sdk-demos/blob/main/resume-generator/.claude/skills/docx/SKILL.md"

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_hello1,node_hello2,node_resume_pipe,node_resume_docx toneBlue
class node_ask_ui,node_ask_socket,node_ask_server toneAmber
class node_chat_ui,node_chat_server,node_chat_store toneMint
class node_email_ui,node_email_server,node_email_ccsdk,node_email_actions,node_email_listeners,node_email_ui_states,node_email_db,node_email_imap toneRose
class node_excel_main,node_excel_preload,node_excel_renderer,node_excel_xlsx toneIndigo
class node_research_agent,node_research_prompts,node_research_utils toneTeal
class node_sdk toneNeutral
```

## Components

### Shared demos

Small onboarding and conversation examples

- [Hello World](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/hello-world/hello-world.ts): starter demo · Minimal TypeScript SDK example · `hello-world/hello-world.ts`
- [Hello World v2](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/hello-world-v2/v2-examples.ts): session demo · Newer session-oriented SDK pattern · `hello-world-v2/v2-examples.ts`

### AskUserQuestion

Browser-mediated clarification preview demo

- [Browser UI](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/ask-user-question-previews/client/App.tsx): react client · Renders question previews and answer controls · `ask-user-question-previews/client/App.tsx`
- [Socket bridge](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/ask-user-question-previews/client/useAgentSocket.ts): ws hook · Manages agent roundtrip over WebSocket · `ask-user-question-previews/client/useAgentSocket.ts`
- [Demo server](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/ask-user-question-previews/server.ts): node server · Hosts the agent loop and websocket endpoint · `ask-user-question-previews/server.ts`

### Simple chat

Minimal web chat loop

- [Chat UI](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/simple-chatapp/client/App.tsx): react client · Conversation window and chat list · `simple-chatapp/client/App.tsx`
- [Chat backend](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/simple-chatapp/server/server.ts): node server · Session management and streamed responses · `simple-chatapp/server/server.ts`
- [Chat store](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/simple-chatapp/server/chat-store.ts): state store · Persists conversation history and sessions · `simple-chatapp/server/chat-store.ts`

### Email agent

Local email automation framework

- [Email UI](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/email-agent/client/App.tsx): react client · Inbox, email viewer, listeners, and assistant chat · `email-agent/client/App.tsx`
- [API server](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/email-agent/server/server.ts): http/ws server · Exposes email, sync, listener, and UI-state endpoints · `email-agent/server/server.ts`
- [CCSDK core](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/email-agent/ccsdk/session.ts): orchestration layer · Coordinates actions, listeners, UI state, queueing, and websocket flow · `email-agent/ccsdk/session.ts`
- [Actions](https://github.com/anthropics/claude-agent-sdk-demos/tree/main/email-agent/agent/custom_scripts/actions): automation plugins · Agent-driven workflows and custom actions · `email-agent/agent/custom_scripts/actions`
- [Listeners](https://github.com/anthropics/claude-agent-sdk-demos/tree/main/email-agent/agent/custom_scripts/listeners): event plugins · Email-triggered automations and classifiers · `email-agent/agent/custom_scripts/listeners`
- [UI states](https://github.com/anthropics/claude-agent-sdk-demos/tree/main/email-agent/agent/custom_scripts/ui-states): dashboard plugins · Custom dashboards and stateful views for the frontend · `email-agent/agent/custom_scripts/ui-states`
- [Email DB](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/email-agent/database/email-db.ts): persistence layer · Schema, search, sync, and IMAP-backed storage · `email-agent/database/email-db.ts`
- [IMAP sync](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/email-agent/database/imap-manager.ts): mail integration · Imports mail from the external email server · `email-agent/database/imap-manager.ts`

### Excel demo

Electron spreadsheet assistant

- [Main process](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/excel-demo/src/main/main.ts): electron main · Privileged app shell and menu wiring · `excel-demo/src/main/main.ts`
- [Preload bridge](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/excel-demo/src/main/preload.ts): electron bridge · Exposes safe APIs from main to renderer · `excel-demo/src/main/preload.ts`
- [Renderer UI](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/excel-demo/src/renderer/App.tsx): react desktop UI · Chat, tool-use, and todo displays · `excel-demo/src/renderer/App.tsx`
- [XLSX skill](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/excel-demo/agent/.claude/skills/xlsx/SKILL.md): spreadsheet tool · Spreadsheet automation skill and recalculation script · `excel-demo/agent/.claude/skills/xlsx/SKILL.md`

### Research agent

Multi-agent research workflow

- [Lead agent](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/research-agent/research_agent/agent.py): workflow coordinator · Decomposes topics and coordinates subagents · `research-agent/research_agent/agent.py`
- [Agent prompts](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/research-agent/research_agent/prompts/lead_agent.txt): prompt set · Specialized roles for lead, researcher, analyst, and writer · `research-agent/research_agent/prompts/lead_agent.txt`
- [Trace utils](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/research-agent/research_agent/utils/subagent_tracker.py): tracking utilities · Transcript capture and subagent tracking · `research-agent/research_agent/utils/subagent_tracker.py`

### Resume generator

Document-generation pipeline

- [Resume pipeline](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/resume-generator/resume-generator.ts): doc generator · Research, assemble, and emit a one-page resume · `resume-generator/resume-generator.ts`
- [DOCX skill](https://github.com/anthropics/claude-agent-sdk-demos/blob/main/resume-generator/.claude/skills/docx/SKILL.md): document tool · Formatting and output generation for Word documents · `resume-generator/.claude/skills/docx/SKILL.md`

### Other components

- **Claude SDK**: agent runtime · Shared Claude Agent SDK dependency used by all demos

## Connections

- Hello World → Claude SDK: uses · Minimal SDK onboarding example
- Hello World v2 → Claude SDK: uses · Session-oriented SDK example
- Browser UI → Socket bridge: events · UI delegates agent interactions to the socket hook
- Socket bridge → Demo server: ws · Bidirectional agent roundtrip
- Demo server → Claude SDK: uses · Runs the clarification/preview agent flow
- Chat UI → Chat backend: http/stream · Sends messages and receives streamed replies
- Chat backend → Chat store: persists · Stores sessions and conversation history
- Chat backend → Claude SDK: uses · Backed by Claude Agent SDK
- Email UI → API server: api/ws · Reads inbox state and live assistant updates
- API server → CCSDK core: delegates · Routes requests into orchestration layer
- CCSDK core → Claude SDK: uses · Claude reasoning and tool execution
- CCSDK core → Actions: runs · Executes user-defined workflows
- CCSDK core → Listeners: reacts · Processes email-triggered automations
- CCSDK core → UI states: drives · Feeds custom dashboard state
- API server → Email DB: reads/writes · Serves email and UI data from persistence
- Email DB → IMAP sync: syncs · Imports messages from external mail server
- Main process → Preload bridge: bridges · Exposes main-process capabilities to renderer
- Preload bridge → Renderer UI: api · Safe renderer access to privileged features
- Renderer UI → Claude SDK: uses · Chat-driven spreadsheet assistant
- Main process → XLSX skill: tools · Invokes spreadsheet automation outside the UI
- Lead agent → Agent prompts: orchestrates · Uses role-specific prompts for subagents
- Lead agent → Trace utils: tracks · Captures transcripts and subagent state
- Lead agent → Claude SDK: uses · Claude-powered research workflow
- Resume pipeline → DOCX skill: formats · Produces the final Word document
- Resume pipeline → Claude SDK: uses · Research and assembly pipeline