How anthropics/claude-quickstarts works
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 Root README · agent.py Agents core · browser_use_demo/loop.py Browser loop · computer_use_demo/loop.py Computer loop
Components 25
Repo & infra
Repository index, shared tooling, and CI delivery.
- Root README · Top-level repository index for the quickstarts collection.
README.md - GitHub Actions · Build and test workflows for the monorepo.
.github/workflows - Python tooling · Root Python project configuration and shared lint/test setup.
pyproject.toml - Claude API · Shared model endpoint used by all agent demos.
Python demos
Reusable agent code and standalone Python quickstarts.
- Agents core · Reusable agent loop, message/history handling, and tool abstractions.
agents/agent.py - Agent tools · Calculator, file, code execution, web search, think, and MCP tools.
agents/tools - Agent utils · Connections, history management, and tool wiring helpers.
agents/utils - Autonomous coding · Initializer and coding agent that advance work across sessions.
autonomous-coding/agent.py - Progress store · Persisted project state and progress tracking built around git.
autonomous-coding/progress.py - Guardrails · 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 · Claude-driven interaction loop and message rendering for browser tasks.
browser-use-demo/browser_use_demo/loop.py - Browser tools · DOM, element, form, text, and keyboard scripts plus browser actions.
browser-use-demo/browser_use_demo/tools/browser.py - Desktop image · X11/VNC/NoVNC desktop environment used to run the browser demo.
browser-use-demo/image/start_all.sh - Computer loop · General computer-use orchestration and Streamlit front end.
computer-use-demo/computer_use_demo/loop.py - Computer tools · Shell, run, edit, computer actions, grouping, and collection helpers.
computer-use-demo/computer_use_demo/tools - Desktop image · Isolated desktop stack for general computer control tasks.
computer-use-demo/image/start_all.sh - Reference loop · Architecture-heavy computer-use loop with preflight, formatting, and trajectory capture.
computer-use-best-practices/computer_use/loop.py - Reference tools · Browser, computer, editor, shell, open-app, batch, and result tools.
computer-use-best-practices/computer_use/tools - Trajectory 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 · Customer support chat interface with sidebar, modal, and nav components.
customer-support-agent/app/page.tsx - Chat route · Claude-facing backend entry point for support conversations.
customer-support-agent/app/api/chat/route.ts - Support KB · Category and source data used to ground support responses.
customer-support-agent/app/lib/customer_support_categories.json - Finance app · Financial analysis and charting interface.
financial-data-analyst/app/page.tsx - Finance route · Analysis endpoint that processes user financial data.
financial-data-analyst/app/api/finance/route.ts - File handling · Upload, parsing, and preview helpers for financial inputs.
financial-data-analyst/utils/fileHandling.ts
Connections 32
- 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.