# Chirp

> A Python web framework for the modern web platform

## Overview

- [Chirp](/chirp/): A Python web framework for HTMX, HTML fragments, streaming HTML, and Server-Sent Events

## Documentation

- [Documentation](/chirp/docs/): Documentation for building HTMX-driven, server-rendered web apps with Chirp

## Releases

- [Chirp 0.1.1](/chirp/releases/0.1.1/): CLI, filesystem routing, reactive blocks, SSE safety, form macros, production support
- [Chirp 0.1.2](/chirp/releases/0.1.2/): Islands V1, chirp-ui integration, auth hardening, Alpine.js support
- [Chirp 0.1.3](/chirp/releases/0.1.3/): Chirp 0.1.3 release
- [Chirp 0.1.4](/chirp/releases/0.1.4/): Enterprise config, health probes, pluggable backends, shell scaffolding
- [Chirp 0.1.5](/chirp/releases/0.1.5/): chirp-ui filter fix — html_attrs, use_chirp_ui auto-registers
- [Chirp 0.1.6](/chirp/releases/0.1.6/): PageComposition API, Suspense + layout chain, htmx debug overlay, kanban_shell example
- [Chirp 0.1.7](/chirp/releases/0.1.7/): App shell guide, islands examples, explicit boost migration, Alpine Focus plugin
- [Chirp 0.1.8](/chirp/releases/0.1.8/): chirp-ui 0.1.5 dependency bump
- [Chirp 0.1.9](/chirp/releases/0.1.9/): Route directory contract, sync-path improvements, route introspection, and synthetic benchmarks
- [Chirp 0.2.0](/chirp/releases/0.2.0/): Devtools overlay, View Transitions tooling, dev browser reload, clearer startup errors, examples reorg, and config default updates
- [Chirp 0.3.0](/chirp/releases/0.3.0/): Security middleware, caching framework, plugin system, schema migrations, i18n, and htmx header correctness
- [Chirp 0.3.1](/chirp/releases/0.3.1/): htmx 4.0 alignment, Speculation Rules API, tiered View Transitions, and bug fixes across standalone examples and framework core
- [Chirp 0.3.2](/chirp/releases/0.3.2/): Bump chirp-ui minimum to 0.2.2
- [Chirp 0.3.3](/chirp/releases/0.3.3/): Fix default CSP for htmx/Alpine.js and bump chirp-ui to 0.2.3
- [Chirp 0.4.0](/chirp/releases/0.4.0/): Refined public API, shell tabs, free-threading safety, performance optimizations, and dependency upgrades
- [Chirp 0.5.0](/chirp/releases/0.5.0/): Strict templates by default, fail-loud OOB regions, Alpine on streaming HTML, agent-grounded chirp-ui 0.5, and a deeper contract-check net.
- [Chirp 0.6.0](/chirp/releases/0.6.0/): Mounted apps, named routes, deeper contract diagnostics, DevTools Swap Doctor, ChirpUI 0.6, Kida 0.8, and production deployment defaults.

## About

- [About](/chirp/docs/about/): Architecture, philosophy, framework comparisons, and thread-safety guidance for Chirp
- [Architecture](/chirp/docs/about/architecture/): Chirp's three-layer architecture
- [When to Use Chirp](/chirp/docs/about/comparison/): When Chirp fits, how it differs from mainstream Python and hypermedia frameworks, and when to choose alternatives
- [Bengal Ecosystem](/chirp/docs/about/ecosystem/): A structured reactive stack — every layer written in pure Python for 3.14t free-threading
- [Philosophy](/chirp/docs/about/philosophy/): The design principles that shape every Chirp decision
- [Thread Safety](/chirp/docs/about/thread-safety/): How Chirp makes data races structurally impossible

## Build Apps

- [Build Apps](/chirp/docs/build-apps/): Pages, fragments, forms, streaming, UI extensions, and request pipelines in Chirp

## Contracts Debugging

- [Contracts and Debugging](/chirp/docs/quality/contracts-debugging/): Contract checks, route-directory validation, DevTools, debug headers, and swap troubleshooting
- [Debugging Swaps](/chirp/docs/quality/contracts-debugging/debugging-swaps/): Use chirp check, debug headers, and DevTools to diagnose broken htmx, OOB, Suspense, and SSE updates
- [OOB Registry & Fail-Loud Rendering](/chirp/docs/quality/contracts-debugging/oob-registry/): Register out-of-band shell regions, mark them optional, and understand BlockNotFoundError
- [Route Directory Contract](/chirp/docs/quality/contracts-debugging/route-contract/): Reserved files, inheritance rules, route kinds, and shell contract for filesystem routes

## Core Concepts

- [Core Concepts](/chirp/docs/about/core-concepts/): Learn the return-type model, app lifecycle, and configuration surface
- [App Lifecycle](/chirp/docs/about/core-concepts/app-lifecycle/): How Chirp's App transitions from mutable setup to frozen runtime
- [Configuration](/chirp/docs/about/core-concepts/configuration/): AppConfig frozen dataclass and all configuration options
- [Return Values](/chirp/docs/about/core-concepts/return-values/): All the types route handlers can return and what they mean

## Deployment

- [Deployment](/chirp/docs/quality/deployment/): Production deployment, Pounce, Docker, Kubernetes, metrics, and runtime configuration
- [Auth Hardening](/chirp/docs/quality/deployment/auth-hardening/): Production checklist for authentication and authorization safety
- [Hybrid Static/Dynamic Freeze](/chirp/docs/quality/deployment/freeze-hybrid/): Static HTML with live-block placeholders backed by an origin
- [Production Deployment](/chirp/docs/quality/deployment/production/): Deploy Chirp apps with Pounce Phase 5 & 6 features

## Examples

- [Examples](/chirp/docs/examples/): Runnable Chirp applications organized by the framework surface they teach
- [Contacts Shell](/chirp/docs/examples/contacts-shell/): Contacts CRUD rebuilt with chirp-ui app shell and mounted pages
- [Contacts](/chirp/docs/examples/contacts/): Plain htmx CRUD with validation, OOB swaps, and response headers
- [Kanban Shell](/chirp/docs/examples/kanban-shell/): App-shell Kanban board with OOB swaps, SSE, auth, and filters
- [RAG Demo](/chirp/docs/examples/rag-demo/): Streaming AI Q&A with cited sources — Chirp's flagship example
- [Returns Gallery](/chirp/docs/examples/returns-gallery/): Every Chirp return type on one page
- [SSE](/chirp/docs/examples/sse/): Minimal Server-Sent Events with strings, SSEEvent, and Fragment payloads
- [Suspense Dashboard](/chirp/docs/examples/suspense-dashboard/): Shell-first initial render with deferred blocks and OOB swaps

## Forms Data

- [Forms and Data](/chirp/docs/build-apps/forms-data/): Form parsing, validation, database access, query helpers, and migrations
- [Database](/chirp/docs/build-apps/forms-data/database/): Async database access with SQLite and PostgreSQL
- [Forms & Validation](/chirp/docs/build-apps/forms-data/forms-validation/): Form parsing, multipart uploads, and validation

## Get Started

- [Get Started](/chirp/docs/get-started/): Install Chirp and build your first HTMX-friendly, server-rendered web application
- [First Fragment App](/chirp/docs/get-started/first-fragment-app/): Build a small htmx-backed Chirp app with Page, Fragment, forms, tests, and chirp check
- [Installation](/chirp/docs/get-started/installation/): Install Chirp and optional extras
- [Project Layout](/chirp/docs/get-started/project-layout/): Recommended directory structure for Chirp apps
- [Quickstart](/chirp/docs/get-started/quickstart/): Build your first Chirp application in 5 minutes

## Html Fragments

- [HTML Fragments](/chirp/docs/build-apps/html-fragments/): Templates, named blocks, Page, Fragment, OOB swaps, and kida integration
- [Filters](/chirp/docs/build-apps/html-fragments/filters/): Register custom template filters and globals
- [Fragment Blocks - Swap-Only Targets](/chirp/docs/build-apps/html-fragments/fragment-blocks/): When to use `{% block %}` vs `{% fragment %}` — the directive for blocks that render only as swap targets
- [Fragments](/chirp/docs/build-apps/html-fragments/fragments/): Render named template blocks independently for htmx
- [Kida Integration](/chirp/docs/build-apps/html-fragments/kida-integration/): How Chirp uses Kida's AST for OOB discovery, block validation, and regions
- [Layout Patterns](/chirp/docs/build-apps/html-fragments/layout-patterns/): Template construct patterns — extends, block, include, call, and outer/inner composition
- [Rendering](/chirp/docs/build-apps/html-fragments/rendering/): How Chirp renders templates via kida

## Pages Navigation

- [Pages and Navigation](/chirp/docs/build-apps/pages-navigation/): Routes, filesystem pages, request handling, and navigation structure
- [Filesystem Routing](/chirp/docs/build-apps/pages-navigation/filesystem-routing/): Route discovery from the pages/ directory with layouts and context cascade
- [Mounting](/chirp/docs/build-apps/pages-navigation/mounting/): Compose reusable plugins and full sub-apps under a URL prefix
- [Request & Response](/chirp/docs/build-apps/pages-navigation/request-response/): The immutable Request and chainable Response API
- [Route Directory Golden Path](/chirp/docs/build-apps/pages-navigation/route-directory/): The recommended way to structure Chirp route directories for app-shell applications
- [Routes](/chirp/docs/build-apps/pages-navigation/routes/): Route registration, methods, and path parameters

## Quality

- [Quality and Operations](/chirp/docs/quality/): Contract checks, testing, debugging, deployment, and production operations for Chirp apps

## Reference

- [Reference](/chirp/docs/reference/): Complete API reference, errors, and configuration
- [API Reference](/chirp/docs/reference/api/): Public API exports and type signatures
- [Errors](/chirp/docs/reference/errors/): Error hierarchy, error handlers, and debug pages

## Request Pipeline

- [Request Pipeline](/chirp/docs/build-apps/request-pipeline/): Middleware for CORS, static files, sessions, auth, CSRF, security headers, and custom request pipelines
- [Built-in Middleware](/chirp/docs/build-apps/request-pipeline/builtin/): CORS, StaticFiles, Sessions, Auth, CSRF, Security, and HTMLInject
- [Custom Middleware](/chirp/docs/build-apps/request-pipeline/custom/): Writing your own middleware with functions and classes
- [Overview](/chirp/docs/build-apps/request-pipeline/overview/): How Chirp's protocol-based middleware works
- [RenderPlan Middleware](/chirp/docs/build-apps/request-pipeline/render-plan/): Inspect rendering decisions from middleware for analytics, caching, and debugging

## Streaming Updates

- [Streaming and Updates](/chirp/docs/build-apps/streaming-updates/): Streaming HTML, Suspense, Server-Sent Events, and reactive updates
- [Streaming HTML](/chirp/docs/build-apps/streaming-updates/html-streaming/): Progressive page rendering with chunked transfer
- [Reactive System](/chirp/docs/build-apps/streaming-updates/reactive-system/): ReactiveBus, DependencyIndex, and reactive_stream — automatic SSE updates from data changes
- [Server-Sent Events](/chirp/docs/build-apps/streaming-updates/server-sent-events/): Push real-time HTML updates to the browser
- [SSE Patterns](/chirp/docs/build-apps/streaming-updates/sse-patterns/): Four update patterns for real-time applications

## Testing

- [Testing](/chirp/docs/quality/testing/): TestClient, fragment assertions, SSE testing, and executable hypermedia checks
- [Assertions](/chirp/docs/quality/testing/assertions/): Fragment and SSE assertion helpers
- [Test Client](/chirp/docs/quality/testing/test-client/): Make requests against your app without a running server

## Tutorials

- [Applied Tutorials](/chirp/docs/tutorials/): Step-by-step walkthroughs that apply Chirp patterns in context
- [Alpine + htmx](/chirp/docs/tutorials/alpine-htmx/): Combine Alpine.js for local state with htmx for server round-trips
- [Coming from Flask](/chirp/docs/tutorials/coming-from-flask/): Translate your Flask knowledge to Chirp
- [htmx Patterns](/chirp/docs/tutorials/htmx-patterns/): Common htmx + Chirp patterns for building interactive apps
- [View Transitions + OOB — The Stable Pattern](/chirp/docs/tutorials/view-transitions-oob/): Reliable pattern for combining htmx-boost, View Transitions, and OOB/SSE updates without flicker

## Ui Extensions

- [UI and Extensions](/chirp/docs/build-apps/ui-extensions/): Shells, accessibility, Alpine, ChirpUI, islands, tools, and extension patterns
- [Accessibility](/chirp/docs/build-apps/ui-extensions/accessibility/): Semantic markup, ARIA, and WCAG alignment for inclusive Chirp apps
- [Alpine.js](/chirp/docs/build-apps/ui-extensions/alpine/): Local UI state with Alpine.js — dropdowns, modals, tabs
- [App Shells](/chirp/docs/build-apps/ui-extensions/app-shell/): Persistent layout with SPA-style navigation and fragment regions
- [Boosted Navigation](/chirp/docs/build-apps/ui-extensions/boosted-navigation/): How hx-boost swaps work in Chirp, when they redirect, and the debug warnings that catch silent failures
- [chirp-ui](/chirp/docs/build-apps/ui-extensions/chirp-ui/): Component library — layout, cards, forms, badges. Kida macros with CSS and themes
- [Islands Contract (V1)](/chirp/docs/build-apps/ui-extensions/islands/): Framework-agnostic contract for isolated client-managed surfaces
- [No-Build High-State](/chirp/docs/build-apps/ui-extensions/no-build-high-state/): Use Chirp islands and state primitives without bundlers
- [Shells](/chirp/docs/build-apps/ui-extensions/shells/): The three root layouts you can extend, when to pick each, and what is not a shell
- [Tools & MCP](/chirp/docs/build-apps/ui-extensions/tools/): Register Python functions as MCP tools for AI agents alongside HTTP routes
- [UI layers & shell regions](/chirp/docs/build-apps/ui-extensions/ui-layers/): Vocabulary for app shell, page chrome, surface chrome, symbolic swap scopes, and stable OOB targets

## Optional

- [llm-full.txt](/chirp/llm-full.txt): Full plain-text content of all pages
- [index.json](/chirp/index.json): Search index with page metadata and excerpts
- [robots.txt](/chirp/robots.txt): Content Signals directives for AI crawlers