understanding-streamlit-architecture — Claude Code skill
understanding-streamlit-architecture is a Claude Code skill that explains Streamlit internals. It covers runtime execution, WebSocket communication, widget state, and React frontend rendering.
Apache-2.0 123 installs ★ 46,474 updated 2026-10-25
npx skills add streamlit/streamlit --skill understanding-streamlit-architecture -a claude-codeWhat understanding-streamlit-architecture does
The skill outlines Streamlit client-server architecture, mapping how the Python runtime talks to the React frontend over bidirectional WebSockets using Protocol Buffers. It details the payload flow between ForwardMsg and BackMsg, covering DeltaGenerator, WidgetStateManager, and element tree representation.
Execution runs top-to-bottom on every rerun. Callbacks like on_change and on_click execute before the main script body. Section updates stay isolated when using @st.fragment, preventing unnecessary full-page reruns. Control flow primitives st.stop(), st.rerun(), and st.switch_page() halt execution by raising internal exceptions.
Every browser tab maintains a distinct AppSession instance with private SessionState. State is not shared across browser sessions.
What it helps with
- debug cross-layer issues between Python backend and React frontend
- trace ForwardMsg and BackMsg payloads across WebSocket connections
- inspect rerun isolation behavior inside
@st.fragment - plan architectural changes across DeltaGenerator and element nodes
Example prompts for the agent
- Explain how widget updates travel from React to SessionState via BackMsg
- Why does st.rerun halt script execution using exceptions?
- How does Streamlit isolate AppSession instances across browser tabs?
How to install understanding-streamlit-architecture
1Skills CLI (Vercel)
npx skills add streamlit/streamlit --skill understanding-streamlit-architecture -a claude-code2Manually: put the files in place
~/.claude/skills/understanding-streamlit-architecture/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/understanding-streamlit-architecture/
1Skills CLI (Vercel)
npx skills add streamlit/streamlit --skill understanding-streamlit-architecture -a codex2Manually: put the files in place
.agents/skills/understanding-streamlit-architecture/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add streamlit/streamlit --skill understanding-streamlit-architecture -a cursor2Manually: put the files in place
.cursor/skills/understanding-streamlit-architecture/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install streamlit/streamlit .claude/skills/understanding-streamlit-architecture2Manually: put the files in place
.github/skills/understanding-streamlit-architecture/SKILL.md1Skills CLI (Vercel)
npx skills add streamlit/streamlit --skill understanding-streamlit-architecture -a gemini-cli2Platform CLI
gemini skills install https://github.com/streamlit/streamlit --path .claude/skills/understanding-streamlit-architectureManually: put the files in place
.devin/skills/understanding-streamlit-architecture/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add streamlit/streamlit --skill understanding-streamlit-architecture -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about understanding-streamlit-architecture
How to install understanding-streamlit-architecture in Claude Code?
Run npx skills add streamlit/streamlit --skill understanding-streamlit-architecture -a claude-code. The skill file installs to ~/.claude/skills/understanding-streamlit-architecture/SKILL.md.
What does understanding-streamlit-architecture cover?
It outlines Streamlit internal subsystems: WebSocket Protocol Buffers communication, script rerun lifecycles, DeltaGenerator queues, and React element rendering.
What triggers a script rerun in Streamlit?
Reruns are triggered by widget interactions, source file changes detected by the watcher, direct st.rerun() calls, or periodic @st.fragment(run_every=...) timers.
Source text
SKILL.md · Apache-2.0
---
name: understanding-streamlit-architecture
description: Explains Streamlit's internal architecture including backend runtime, frontend rendering, and WebSocket communication. Use when debugging cross-layer issues, understanding how features work end-to-end, planning architectural changes, or onboarding to the codebase. Covers ForwardMsg/BackMsg protocol, script rerun model, element tree, widget state management, and the delta-path rules shared by the frontend and the agent snapshot.
---
# Understanding Streamlit architecture
Streamlit is a client-server application with bidirectional WebSocket communication using Protocol Buffers.
Use this file as a quick mental model and navigation index; use `references/backend.md`, `references/frontend.md`, and `references/communication.md` for implementation details.
## Concepts glossary
| Concept | Description | Key files |
|---------|-------------|-----------|
| **Command** | Any function exposed in Streamlit's public API (`st.*` namespace). Commands can create elements/widgets, control execution flow, or configure app behavior. | `lib/streamlit/delta_generator.py`, `lib/streamlit/elements/`, `lib/streamlit/commands/` |
| **Element** | Umbrella term for all UI components in Streamlit: widgets, containers, and display elements. Represented in `Element.proto` as a `oneof` union of ~50+ types. | `proto/streamlit/proto/Element.proto`, `lib/streamlit/elements/` |
| **Widget** | Interactive element (button, slider, text_input) that typically triggers a rerun on user interaction. Value accessible via return value or `st.session_state`. Widgets that support `on_change="ignore"` update in the browser without rerunning until something else does. Some elements become widgets conditionally (e.g., dataframe/chart with `on_select`). | `lib/streamlit/elements/widgets/`, `frontend/lib/src/components/widgets/` |
| **Display Element** | Non-interactive element (text, markdown, image, chart) that renders content without triggering reruns by itself. | `lib/streamlit/elements/`, `frontend/lib/src/components/elements/` |
| **Container** | Layout block that groups elements spatially (sidebar, columns, expander, tabs, form). Represented as `BlockNode` in the element tree. | `lib/streamlit/elements/layouts.py`, `Block.proto` |
| **DeltaGenerator** | The `st` object; API entry point that queues UI deltas. Uses mixin pattern to compose all `st.*` commands. | `lib/streamlit/delta_generator.py` |
| **Session State** | Per-session dictionary (`st.session_state`) persisting data across reruns. Stores widget values and user variables. | `lib/streamlit/runtime/state/session_state.py` |
| **Rerun** | Re-execution of the user script for the current page. Triggered by widget interactions, `st.rerun()`, file changes, or fragment timers. Rebuilds the element tree while preserving session state. | `lib/streamlit/runtime/scriptrunner/script_runner.py`, `lib/streamlit/commands/execution_control.py` |
| **Form** | Container (`st.form`) that batches widget inputs, deferring reruns until form submission. | `lib/streamlit/elements/form.py`, `WidgetStateManager.ts` |
| **Fragment** | Decorator (`@st.fragment`) enabling partial reruns of specific UI sections without full script re-execution. | `lib/streamlit/runtime/fragment.py` |
| **Caching** | Decorators (`@st.cache_data`, `@st.cache_resource`) that memoize function results to avoid redundant computation. | `lib/streamlit/runtime/caching/` |
| **Pages** | Multipage app system using `st.navigation()` and `st.Page()` or auto-discovery from `pages/` directory. | `lib/streamlit/navigation/`, `lib/streamlit/runtime/pages_manager.py` |
| **Config** | App configuration via `.streamlit/config.toml` controlling server, client, and theme settings. | `lib/streamlit/config.py`, `lib/streamlit/config_option.py` |
| **Theming** | Customizable UI themes (Light/Dark/Custom) defined in config or via theme editor. | `lib/streamlit/runtime/theme_util.py`, `frontend/lib/src/theme/` |
| **Secrets** | Secure credential storage via `.streamlit/secrets.toml` (local) or platform settings (deployed). Accessed via `st.secrets`. | `lib/streamlit/runtime/secrets.py` |
| **Connection** | Database/service abstraction (`st.connection`) with built-in caching and secrets integration. | `lib/streamlit/connections/` |
| **Custom Components** | User-built extensions using React/iframe. **v1 (legacy)**: `declare_component()` API. **v2 (current)**: Bidirectional components with improved state management. | `frontend/component-lib/`, `frontend/component-v2-lib/`, `lib/streamlit/components/v1/`, `lib/streamlit/components/v2/` |
| **Static File Serving** | Files in `static/` directory served directly via `/app/static/*` (when static serving is enabled). | `lib/streamlit/web/server/server.py`, `lib/streamlit/web/server/starlette/starlette_routes.py` |
| **App Testing** | Testing framework (`AppTest`) for simulating user interactions and inspecting rendered output. | `lib/streamlit/testing/` |
## Core mental model
```mermaid
flowchart TB
subgraph Backend["Backend (Python)"]
Script[User Script]
DG[DeltaGenerator]
Runtime[Runtime/AppSession]
end
subgraph Protocol["WebSocket + Protobuf"]
FM[ForwardMsg]
BM[BackMsg]
end
subgraph Frontend["Frontend (React)"]
App[App.tsx]
Tree[AppRoot Tree]
Renderer[ElementNodeRenderer]
WSM[WidgetStateManager]
end
Script --> DG
DG --> FM
FM --> App
App --> Tree
Tree --> Renderer
Renderer --> WSM
WSM -->|User interaction| BM
BM --> Runtime
Runtime -->|Rerun| Script
```
**Key insight**: Script execution is rerun-driven: most widget interactions trigger reruns (full app or fragment-scoped). State persists via `st.session_state` and caching decorators.
## Execution model
Streamlit's execution model differs from traditional web frameworks:
**Rerun triggers**:
1. **Widget interaction**: User clicks button, moves slider, etc. (widgets with `on_change="ignore"` update without a rerun)
2. **Source code change**: File watcher detects script modification
3. **`st.rerun()`**: Explicit programmatic rerun
4. **Fragment timer**: `@st.fragment(run_every=...)` periodic reruns
**Execution order nuances**:
- Scripts execute **top-to-bottom** on every rerun
- **Callbacks first**: `on_change`/`on_click` handlers run *before* the main script body
- **Fragments typically isolate reruns**: Widget interactions inside `@st.fragment` usually rerun only that fragment
- **Keyed fragment reruns**: `st.rerun("<key>")` from a widget callback reruns only the named `@st.fragment(key=...)` fragment(s)
- **Control flow exceptions**: `st.stop()`, `st.rerun()`, `st.switch_page()` raise exceptions to halt/redirect execution
**Session isolation**:
- Each browser tab = separate `AppSession` with its own `SessionState`
- Refreshing the page creates a new session (unless reconnecting within TTL)
- No shared state between sessions (use external storage for multi-user state)
**What persists across reruns** (within a session):
- `st.session_state` values
- Cached function results (`@st.cache_data`, `@st.cache_resource`)
- Uploaded files
- Fragment registrations
**What resets on each rerun**:
- Local variables in script
- Widget return values (re-read from `SessionState`)
- Element tree (rebuilt from scratch, then diffed)
## Architecture layers
### Backend (Python)
| Component | File | Purpose |
|-----------|------|---------|
| Runtime | `lib/streamlit/runtime/runtime.py` | Singleton managing app lifecycle and sessions |
| AppSession | `lib/streamlit/runtime/app_session.py` | Per browser tab or agent API session: ScriptRunner + SessionState + ForwardMsgQueue |
| ScriptRunner | `lib/streamlit/runtime/scriptrunner/script_runner.py` | Executes user scripts in separate thread |
| DeltaGenerator | `lib/streamlit/delta_generator.py` | API entry point using mixin pattern |
| SessionState | `lib/streamlit/runtime/state/session_state.py` | Widget values and user variables |
| Elements | `lib/streamlit/elements/` | Backend implementation of `st.*` commands |
**For backend deep dive**: See [references/backend.md](references/backend.md)
### Frontend (TypeScript/React)
| Component | File | Purpose |
|-----------|------|---------|
| App | `frontend/app/src/App.tsx` | Central orchestrator |
| AppRoot | `frontend/lib/src/render-tree/AppRoot.ts` | Immutable element tree with 4 containers |
| ElementNodeRenderer | `frontend/lib/src/components/core/Block/ElementNodeRenderer.tsx` | Maps protos to React components |
| WidgetStateManager | `frontend/lib/src/WidgetStateManager.ts` | Widget state, forms, query params |
| ConnectionManager | `frontend/connection/src/ConnectionManager.ts` | WebSocket state machine |
**For frontend deep dive**: See [references/frontend.md](references/frontend.md)
### Communication (Protobuf)
| Proto | Purpose |
|-------|---------|
| `ForwardMsg.proto` | Server to client: deltas, session events, navigation |
| `BackMsg.proto` | Client to server: rerun requests with widget states |
| `Element.proto` | ~50+ element types in `oneof type` union |
| `WidgetStates.proto` | Widget values: `trigger_value`, `string_value`, `bool_value`, etc. |
**Location**: `proto/streamlit/proto/`
**For protocol deep dive**: See [references/communication.md](references/communication.md)
## Essential concepts (quick map)
- **Layout system**: Width/height parameters for elements, flexbox containers, and responsive sizing.
- Deep dive: [references/layout.md](references/layout.md)
- **Script rerun model**: Widget interaction -> `BackMsg` (`ClientState`) -> backend updates `SessionState` -> script rerun -> `ForwardMsg` deltas.
- Deep dive: `references/communication.md#widget-interaction-to-script-rerun`
- **Delta path system**: Elements are addressed by delta paths (for example `[0, 2, 3]`) to support efficient tree updates. The frontend and the agent snapshot apply the same placement rules.
- Deep dive: `references/communication.md#delta-ui-changes`
- **`active_script_hash` semantics**: `ForwardMsg.metadata.active_script_hash` scopes node ownership across multipage and fragment reruns.
- Deep dive: `references/communication.md#forwardmsg-metadata-active_script_hash`
- **Agent element descriptions**: A command can attach JSON on `ForwardMsg.metadata.agent_props`.
- Deep dive: `references/communication.md#agent-command-descriptions`
- **Element tree structure**: Frontend `AppRoot` maintains `main`, `sidebar`, `event`, and `bottom` containers with `BlockNode`/`ElementNode`.
- Deep dive: `references/frontend.md#element-tree-frontendlibsrcrender-tree`
- **Element identity semantics**: Delta paths decide where a node lives; element IDs decide whether stateful elements can reconnect to prior state after remounts.
- Deep dive: `references/element-identity.md`
- **Fragments (`@st.fragment`)**: Fragment interactions usually trigger fragment-scoped reruns and update only affected regions. A widget callback can also target named fragments with `st.rerun("<key>")` when the fragment was declared with `@st.fragment(key=...)`.
- Deep dive: [references/backend.md](references/backend.md#fragment-system-stfragment)
## Shared delta-path semantics
The browser and the agent interaction API both place nodes by applying `ForwardMsg` deltas in order. The frontend does this in `AppRoot` (`frontend/lib/src/render-tree/`). The interaction API does it in `merge_deltas` (`lib/streamlit/runtime/agent/tree.py`) when it builds a snapshot.
They follow the same placement rules. A delta path addresses a node. A block of the same type keeps its children, and a different block type or dialog identity replaces them. When those rules change, update both sides.
The two trees are not the same structure. The frontend merges deltas as they arrive, and it also filters by script hash, uses the message cache, and keeps transient nodes such as spinners. The snapshot merges the messages that remain after the run and its fragments settle, then drops nodes and props with no semantic value, such as `st.empty`, `st.space`, skeletons, spinners, width, and height. Leave the implementations separate. Do not require the JSON tree to match the render tree node for node.
## Element identity
- **Delta path** controls where a node is placed in the render tree.
- **Element ID** controls whether a stateful element can reconnect to prior state after remounts.
- **Widgets** use the ID to connect frontend `WidgetStateManager` state, `BackMsg.WidgetStates`, backend `SessionState`, callbacks, and `st.session_state`.
- **Some non-widgets** also use IDs for frontend-only reconstruction (for example chart view state or media autoplay guards).
- **Delta-path changes can remount elements**, but a stable `element.id` can still let React preserve a leaf when it remains under the same rendered parent list.
Deep dive: `references/element-identity.md`
## Key implementation patterns
- **Backend mixin composition**: `DeltaGenerator` composes `st.*` API via mixins.
- Deep dive: `references/backend.md#deltagenerator-libstreamlitdelta_generatorpy`
- **Frontend visitor pattern**: Render-tree updates/staleness cleanup use visitors.
- Deep dive: `references/frontend.md#visitor-pattern`
- **Message deduplication**: `ForwardMsg.hash` + `ref_hash` with frontend `ForwardMsgCache` reduces bandwidth.
- Deep dive: `references/communication.md#message-caching`
## Quick reference: adding features
1. **Proto definition**: `proto/streamlit/proto/<Element>.proto`
2. **Register in Element.proto**: Add to `oneof type`
3. **Backend mixin**: `lib/streamlit/elements/<element>.py`
4. **Frontend component**: `frontend/lib/src/components/elements/<Element>/` or `frontend/lib/src/components/widgets/<Element>/` (depending on element vs widget)
5. **Register in ElementNodeRenderer**: Add case to switch statement
6. **Compile protos**: `make protobuf`
See `wiki/new-feature-guide.md` for a detailed implementation guide.
## Maintaining this documentation
When making changes that impact any of the concepts documented here (Runtime, AppSession, DeltaGenerator, element tree, communication protocol, element identity, etc.), update the relevant sections in this skill's files (`SKILL.md`, `references/backend.md`, `references/frontend.md`, `references/communication.md`, `references/element-identity.md`) to keep them accurate.
© streamlit · Apache-2.0 · streamlit/streamlit