# anthropics/claude-quickstarts architecture

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

- Interactive diagram: https://gitdiagram.com/anthropics/claude-quickstarts
- Repository: https://github.com/anthropics/claude-quickstarts
- Video tour (about a minute): https://gitdiagram.com/anthropics/claude-quickstarts/video

## Overview

1. **Repository shape**
   This is a monorepo of independent Claude quickstarts, not one application. Each top-level folder is a self-contained demo with its own runtime, dependencies, UI, and tests. The root `README.md` serves as an index; the real architecture lives inside each quickstart.

2. **Shared intent across projects**
   All examples center on a Claude-powered agent or assistant that sits between a user and some domain-specific capability: customer support knowledge retrieval, finance analysis, browser automation, computer control, or autonomous coding. The common architectural pattern is: UI or CLI input → orchestration loop → Claude API call(s) → tool/action execution → rendered result back to the user.

3. **Python agent framework: `agents/`**
   The `agents` package is a reusable Python agent layer with a generic `agent.py`, tool abstractions, and utility modules for message/history handling and connections. Its tool set includes calculator, file, code execution, web search, “think”/reasoning, and MCP integration, so it functions as the shared agent runtime for experiments and demos rather than a product app.

4. **Autonomous coding subsystem: `autonomous-coding/`**
   This project is a two-agent system: an initializer/structurer and a coding agent that iteratively advances a project over multiple sessions. Key architectural boundaries are the prompt templates, `progress.py` for persisted state, `security.py` for guardrails, and a client/agent split that keeps conversation orchestration separate from execution. The persistence mechanism is git-based progress tracking rather than a database.

5. **Browser automation subsystem: `browser-use-demo/`**
   This demo combines a Python app with a bundled desktop/browser environment. The `browser_use_demo` package contains the interaction loop, message handling/rendering, and browser tools; the `image/` directory defines a containerized Linux desktop with X11/VNC/NoVNC startup scripts and a static HTTP server. The browser tool layer is backed by Playwright-style DOM, element, form, text, and keyboard scripts, so the data flow is Claude → browser tool calls → DOM/state extraction → UI feedback.

6. **Computer control demo: `computer-use-demo/`**
   Similar to the browser demo, this is an agent loop plus local tools, but the scope is general computer use rather than just the browser. The toolset includes shell/bash, run, edit, computer actions, and grouping/collection helpers. The `image/` folder again provides a containerized desktop stack, so the important boundary is between the agent process and the isolated GUI environment it manipulates.

7. **Computer-use reference implementation: `computer-use-best-practices/`**
   This is the most architecture-heavy Python project in the repo. It separates the agent loop, rendering/formatting, image handling, preflight checks, and trajectory recording into distinct modules. Tools are explicit and granular: browser, computer, editor, shell, open-app, batch execution, and result handling. It also includes a `dev_ui/` area with a trajectory viewer and tool panel, showing a clear split between runtime execution and observability/debugging.

8. **Customer support web app: `customer-support-agent/`**
   This is a Next.js/TypeScript frontend with an API route at `app/api/chat/route.ts` that acts as the Claude-facing backend entry point. The UI is composed of sidebar, chat area, modal, and top-nav components; the knowledge base/category data lives in `app/lib/customer_support_categories.json`. The main data flow is browser UI → chat API route → Claude response → rendered support conversation, with no separate backend service visible in the tree.

9. **Financial analyst web app: `financial-data-analyst/`**
   Another Next.js app, but optimized for analysis and visualization. The app contains a finance API route, chart rendering components, file preview support, and chart-related shared types/utilities. The architecture centers on user-provided financial data flowing through upload/handling utilities into analysis endpoints and then into chart/UI presentation, with toasts and layout components supporting the interactive workflow.

10. **Repo-level infrastructure and delivery**
   CI is handled by GitHub Actions in `.github/workflows`, with separate build and test workflows plus reusable build steps. The presence of Dockerfiles, Compose files, setup scripts, and environment templates across demos shows that deployment is mostly local/dev-container oriented, not a single shared production backend. The root `pyproject.toml` and lint/test configs support cross-project Python tooling, while the TypeScript apps each manage their own package/config stack.

11. **How to diagram this repo accurately**
   The correct diagram should show a collection of sibling projects under one repository, not a layered system with shared runtime dependencies. Draw each quickstart as its own bounded context with its own UI, agent loop, tools, and environment. Shared external dependency is Claude API; project-specific external dependencies include browser/desktop virtualization, git, Playwright/browser automation, Streamlit, and Next.js serverless routes.

Main entry points: [`README.md`](https://github.com/anthropics/claude-quickstarts/blob/main/README.md) (Root README), [`agents/agent.py`](https://github.com/anthropics/claude-quickstarts/blob/main/agents/agent.py) (Agents core), [`browser-use-demo/browser_use_demo/loop.py`](https://github.com/anthropics/claude-quickstarts/blob/main/browser-use-demo/browser_use_demo/loop.py) (Browser loop), [`computer-use-demo/computer_use_demo/loop.py`](https://github.com/anthropics/claude-quickstarts/blob/main/computer-use-demo/computer_use_demo/loop.py) (Computer loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Repo & infra"]
  node_readme["Root README<br/>index<br/>[README.md]"]
  node_ci["GitHub Actions<br/>ci<br/>[workflows]"]
  node_pytooling["Python tooling<br/>package config<br/>[pyproject.toml]"]
  node_claude_api(("Claude API<br/>external service"))
end

subgraph group_python["Python demos"]
  node_agents_runtime["Agents core<br/>python agent framework<br/>[agent.py]"]
  node_agents_tools["Agent tools<br/>toolkit"]
  node_agents_utils["Agent utils<br/>support modules"]
  node_autonomous_coding["Autonomous coding<br/>two-agent system<br/>[agent.py]"]
  node_autonomous_state["Progress store<br/>git state<br/>[progress.py]"]
  node_autonomous_guardrails["Guardrails<br/>security layer<br/>[security.py]"]
end

subgraph group_desktop["Desktop agents"]
  node_browser_loop["Browser loop<br/>agent loop<br/>[loop.py]"]
  node_browser_tools["Browser tools<br/>playwright tools<br/>[browser.py]"]
  node_browser_image["Desktop image<br/>containerized GUI<br/>[start_all.sh]"]
  node_computer_loop["Computer loop<br/>agent loop<br/>[loop.py]"]
  node_computer_tools["Computer tools<br/>gui tools"]
  node_computer_image["Desktop image<br/>containerized GUI<br/>[start_all.sh]"]
  node_best_practices_loop["Reference loop<br/>agent runtime<br/>[loop.py]"]
  node_best_practices_tools["Reference tools<br/>tool suite"]
  node_trajectory_viewer["Trajectory UI<br/>observability ui<br/>[app.py]"]
end

subgraph group_web["Web apps"]
  node_support_ui["Support app<br/>next.js ui<br/>[page.tsx]"]
  node_support_api["Chat route<br/>serverless api<br/>[route.ts]"]
  node_support_kb["Support KB<br/>knowledge base"]
  node_finance_ui["Finance app<br/>next.js ui<br/>[page.tsx]"]
  node_finance_api["Finance route<br/>serverless api<br/>[route.ts]"]
  node_finance_utils["File handling<br/>analysis utils<br/>[fileHandling.ts]"]
end

node_readme -->|"indexes"| node_agents_runtime
node_readme -->|"indexes"| node_autonomous_coding
node_readme -->|"indexes"| node_browser_loop
node_readme -->|"indexes"| node_computer_loop
node_readme -->|"indexes"| node_best_practices_loop
node_readme -->|"indexes"| node_support_ui
node_readme -->|"indexes"| node_finance_ui
node_ci -->|"checks"| node_agents_runtime
node_ci -->|"tests"| node_browser_loop
node_ci -->|"tests"| node_computer_loop
node_ci -->|"tests"| node_best_practices_loop
node_agents_runtime -->|"uses"| node_agents_tools
node_agents_runtime -->|"uses"| node_agents_utils
node_agents_runtime -->|"calls"| node_claude_api
node_autonomous_coding -->|"persists"| node_autonomous_state
node_autonomous_coding -->|"constrains"| node_autonomous_guardrails
node_autonomous_coding -->|"calls"| node_claude_api
node_browser_loop -->|"executes"| node_browser_tools
node_browser_loop -->|"targets"| node_browser_image
node_browser_loop -->|"calls"| node_claude_api
node_computer_loop -->|"executes"| node_computer_tools
node_computer_loop -->|"targets"| node_computer_image
node_computer_loop -->|"calls"| node_claude_api
node_best_practices_loop -->|"executes"| node_best_practices_tools
node_best_practices_loop -->|"records"| node_trajectory_viewer
node_best_practices_loop -->|"calls"| node_claude_api
node_support_ui -->|"requests"| node_support_api
node_support_api -->|"grounds"| node_support_kb
node_support_api -->|"calls"| node_claude_api
node_finance_ui -->|"requests"| node_finance_api
node_finance_api -->|"uses"| node_finance_utils
node_finance_api -->|"calls"| node_claude_api

click node_readme "https://github.com/anthropics/claude-quickstarts/blob/main/README.md"
click node_ci "https://github.com/anthropics/claude-quickstarts/blob/main/.github/workflows"
click node_pytooling "https://github.com/anthropics/claude-quickstarts/blob/main/pyproject.toml"
click node_agents_runtime "https://github.com/anthropics/claude-quickstarts/blob/main/agents/agent.py"
click node_agents_tools "https://github.com/anthropics/claude-quickstarts/tree/main/agents/tools"
click node_agents_utils "https://github.com/anthropics/claude-quickstarts/tree/main/agents/utils"
click node_autonomous_coding "https://github.com/anthropics/claude-quickstarts/blob/main/autonomous-coding/agent.py"
click node_autonomous_state "https://github.com/anthropics/claude-quickstarts/blob/main/autonomous-coding/progress.py"
click node_autonomous_guardrails "https://github.com/anthropics/claude-quickstarts/blob/main/autonomous-coding/security.py"
click node_browser_loop "https://github.com/anthropics/claude-quickstarts/blob/main/browser-use-demo/browser_use_demo/loop.py"
click node_browser_tools "https://github.com/anthropics/claude-quickstarts/blob/main/browser-use-demo/browser_use_demo/tools/browser.py"
click node_browser_image "https://github.com/anthropics/claude-quickstarts/blob/main/browser-use-demo/image/start_all.sh"
click node_computer_loop "https://github.com/anthropics/claude-quickstarts/blob/main/computer-use-demo/computer_use_demo/loop.py"
click node_computer_tools "https://github.com/anthropics/claude-quickstarts/tree/main/computer-use-demo/computer_use_demo/tools"
click node_computer_image "https://github.com/anthropics/claude-quickstarts/blob/main/computer-use-demo/image/start_all.sh"
click node_best_practices_loop "https://github.com/anthropics/claude-quickstarts/blob/main/computer-use-best-practices/computer_use/loop.py"
click node_best_practices_tools "https://github.com/anthropics/claude-quickstarts/tree/main/computer-use-best-practices/computer_use/tools"
click node_trajectory_viewer "https://github.com/anthropics/claude-quickstarts/blob/main/computer-use-best-practices/dev_ui/trajectory_viewer/app.py"
click node_support_ui "https://github.com/anthropics/claude-quickstarts/blob/main/customer-support-agent/app/page.tsx"
click node_support_api "https://github.com/anthropics/claude-quickstarts/blob/main/customer-support-agent/app/api/chat/route.ts"
click node_support_kb "https://github.com/anthropics/claude-quickstarts/blob/main/customer-support-agent/app/lib/customer_support_categories.json"
click node_finance_ui "https://github.com/anthropics/claude-quickstarts/blob/main/financial-data-analyst/app/page.tsx"
click node_finance_api "https://github.com/anthropics/claude-quickstarts/blob/main/financial-data-analyst/app/api/finance/route.ts"
click node_finance_utils "https://github.com/anthropics/claude-quickstarts/blob/main/financial-data-analyst/utils/fileHandling.ts"

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_readme,node_ci,node_pytooling,node_claude_api toneBlue
class node_agents_runtime,node_agents_tools,node_agents_utils,node_autonomous_coding,node_autonomous_state,node_autonomous_guardrails toneAmber
class node_browser_loop,node_browser_tools,node_browser_image,node_computer_loop,node_computer_tools,node_computer_image,node_best_practices_loop,node_best_practices_tools,node_trajectory_viewer toneMint
class node_support_ui,node_support_api,node_support_kb,node_finance_ui,node_finance_api,node_finance_utils toneRose
```

## Components

### Repo & infra

Repository index, shared tooling, and CI delivery.

- [Root README](https://github.com/anthropics/claude-quickstarts/blob/main/README.md): index · Top-level repository index for the quickstarts collection. · `README.md`
- [GitHub Actions](https://github.com/anthropics/claude-quickstarts/blob/main/.github/workflows): ci · Build and test workflows for the monorepo. · `.github/workflows`
- [Python tooling](https://github.com/anthropics/claude-quickstarts/blob/main/pyproject.toml): package config · Root Python project configuration and shared lint/test setup. · `pyproject.toml`
- **Claude API**: external service · Shared model endpoint used by all agent demos.

### Python demos

Reusable agent code and standalone Python quickstarts.

- [Agents core](https://github.com/anthropics/claude-quickstarts/blob/main/agents/agent.py): python agent framework · Reusable agent loop, message/history handling, and tool abstractions. · `agents/agent.py`
- [Agent tools](https://github.com/anthropics/claude-quickstarts/tree/main/agents/tools): toolkit · Calculator, file, code execution, web search, think, and MCP tools. · `agents/tools`
- [Agent utils](https://github.com/anthropics/claude-quickstarts/tree/main/agents/utils): support modules · Connections, history management, and tool wiring helpers. · `agents/utils`
- [Autonomous coding](https://github.com/anthropics/claude-quickstarts/blob/main/autonomous-coding/agent.py): two-agent system · Initializer and coding agent that advance work across sessions. · `autonomous-coding/agent.py`
- [Progress store](https://github.com/anthropics/claude-quickstarts/blob/main/autonomous-coding/progress.py): git state · Persisted project state and progress tracking built around git. · `autonomous-coding/progress.py`
- [Guardrails](https://github.com/anthropics/claude-quickstarts/blob/main/autonomous-coding/security.py): security layer · Safety checks and execution constraints for autonomous coding. · `autonomous-coding/security.py`

### Desktop agents

Browser and computer-control demos with bundled GUI environments.

- [Browser loop](https://github.com/anthropics/claude-quickstarts/blob/main/browser-use-demo/browser_use_demo/loop.py): agent loop · Claude-driven interaction loop and message rendering for browser tasks. · `browser-use-demo/browser_use_demo/loop.py`
- [Browser tools](https://github.com/anthropics/claude-quickstarts/blob/main/browser-use-demo/browser_use_demo/tools/browser.py): playwright tools · DOM, element, form, text, and keyboard scripts plus browser actions. · `browser-use-demo/browser_use_demo/tools/browser.py`
- [Desktop image](https://github.com/anthropics/claude-quickstarts/blob/main/browser-use-demo/image/start_all.sh): containerized GUI · X11/VNC/NoVNC desktop environment used to run the browser demo. · `browser-use-demo/image/start_all.sh`
- [Computer loop](https://github.com/anthropics/claude-quickstarts/blob/main/computer-use-demo/computer_use_demo/loop.py): agent loop · General computer-use orchestration and Streamlit front end. · `computer-use-demo/computer_use_demo/loop.py`
- [Computer tools](https://github.com/anthropics/claude-quickstarts/tree/main/computer-use-demo/computer_use_demo/tools): gui tools · Shell, run, edit, computer actions, grouping, and collection helpers. · `computer-use-demo/computer_use_demo/tools`
- [Desktop image](https://github.com/anthropics/claude-quickstarts/blob/main/computer-use-demo/image/start_all.sh): containerized GUI · Isolated desktop stack for general computer control tasks. · `computer-use-demo/image/start_all.sh`
- [Reference loop](https://github.com/anthropics/claude-quickstarts/blob/main/computer-use-best-practices/computer_use/loop.py): agent runtime · Architecture-heavy computer-use loop with preflight, formatting, and trajectory capture. · `computer-use-best-practices/computer_use/loop.py`
- [Reference tools](https://github.com/anthropics/claude-quickstarts/tree/main/computer-use-best-practices/computer_use/tools): tool suite · Browser, computer, editor, shell, open-app, batch, and result tools. · `computer-use-best-practices/computer_use/tools`
- [Trajectory UI](https://github.com/anthropics/claude-quickstarts/blob/main/computer-use-best-practices/dev_ui/trajectory_viewer/app.py): observability ui · Dev UI for inspecting runs, tools, and recorded trajectories. · `computer-use-best-practices/dev_ui/trajectory_viewer/app.py`

### Web apps

Next.js quickstarts that expose Claude through UI and API routes.

- [Support app](https://github.com/anthropics/claude-quickstarts/blob/main/customer-support-agent/app/page.tsx): next.js ui · Customer support chat interface with sidebar, modal, and nav components. · `customer-support-agent/app/page.tsx`
- [Chat route](https://github.com/anthropics/claude-quickstarts/blob/main/customer-support-agent/app/api/chat/route.ts): serverless api · Claude-facing backend entry point for support conversations. · `customer-support-agent/app/api/chat/route.ts`
- [Support KB](https://github.com/anthropics/claude-quickstarts/blob/main/customer-support-agent/app/lib/customer_support_categories.json): knowledge base · Category and source data used to ground support responses. · `customer-support-agent/app/lib/customer_support_categories.json`
- [Finance app](https://github.com/anthropics/claude-quickstarts/blob/main/financial-data-analyst/app/page.tsx): next.js ui · Financial analysis and charting interface. · `financial-data-analyst/app/page.tsx`
- [Finance route](https://github.com/anthropics/claude-quickstarts/blob/main/financial-data-analyst/app/api/finance/route.ts): serverless api · Analysis endpoint that processes user financial data. · `financial-data-analyst/app/api/finance/route.ts`
- [File handling](https://github.com/anthropics/claude-quickstarts/blob/main/financial-data-analyst/utils/fileHandling.ts): analysis utils · Upload, parsing, and preview helpers for financial inputs. · `financial-data-analyst/utils/fileHandling.ts`

## Connections

- Root README → Agents core: indexes · Repository index points to the reusable agent framework.
- Root README → Autonomous coding: indexes · Repository index points to the autonomous coding demo.
- Root README → Browser loop: indexes · Repository index points to the browser automation demo.
- Root README → Computer loop: indexes · Repository index points to the computer-use demo.
- Root README → Reference loop: indexes · Repository index points to the reference computer-use implementation.
- Root README → Support app: indexes · Repository index points to the support quickstart.
- Root README → Finance app: indexes · Repository index points to the finance quickstart.
- GitHub Actions → Agents core: checks · CI validates the shared Python agent code.
- GitHub Actions → Browser loop: tests · CI runs browser demo validation.
- GitHub Actions → Computer loop: tests · CI runs computer-use demo validation.
- GitHub Actions → Reference loop: tests · CI runs reference implementation tests.
- Agents core → Agent tools: uses · Core agent loop invokes tool implementations.
- Agents core → Agent utils: uses · Core agent loop relies on utility modules.
- Agents core → Claude API: calls · Agent framework sends prompts and receives model responses.
- Autonomous coding → Progress store: persists · Autonomous coding tracks progress across sessions.
- Autonomous coding → Guardrails: constrains · Security layer limits execution and mutation scope.
- Autonomous coding → Claude API: calls · Two-agent workflow depends on Claude for planning and coding.
- Browser loop → Browser tools: executes · Loop issues browser actions through the tool layer.
- Browser loop → Desktop image: targets · Agent manipulates the isolated desktop/browser environment.
- Browser loop → Claude API: calls · Browser agent delegates decisions to Claude.
- Computer loop → Computer tools: executes · Loop uses local computer-control tools.
- Computer loop → Desktop image: targets · Agent operates inside the isolated desktop environment.
- Computer loop → Claude API: calls · Computer-use agent delegates decisions to Claude.
- Reference loop → Reference tools: executes · Reference runtime invokes its explicit tool suite.
- Reference loop → Trajectory UI: records · Runtime feeds observability and trajectory inspection.
- Reference loop → Claude API: calls · Reference agent loop depends on Claude responses.
- Support app → Chat route: requests · Frontend sends chat traffic to the API route.
- Chat route → Support KB: grounds · Chat route uses knowledge base data in responses.
- Chat route → Claude API: calls · Support backend forwards prompts to Claude.
- Finance app → Finance route: requests · Finance frontend submits analysis work to the API route.
- Finance route → File handling: uses · Analysis route depends on file handling utilities.
- Finance route → Claude API: calls · Finance backend forwards analysis prompts to Claude.