anthropics/claude-agent-sdk-demos

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.