AI-assisted development

Stario works well with agents when the repo has one obvious shape: a small bootstrap, explicit routes, feature folders, pure views, and one local instruction file. This how-to is the shortest path from an empty folder to a Stario app an agent can extend without guessing.

1. Create the project

bash

uv init --app my-app

cd my-app

uv add "stario>=4,<5"

uv add --dev ruff pyright pytest pytest-asyncio

curl -o AGENTS.md https://stario.dev/AGENTS.md

That AGENTS.md file is the important part. It contains the commands, project layout, Stario invariants, Datastar guidance, and common mistakes. In many editors, that one file is enough agent context.

If your tool wants web context too, point it at llms.txt for a short doc index or llms-full.txt for compact framework notes.

2. Start with the product shape

Use the layout in AGENTS.md from the first commit. Do not start with a flat root-level main.py, routes.py, and handlers.py and plan to split later.

The fastest path is to copy examples/chat-room, rename the features, and delete what you do not need. It shows the structure Stario apps should grow into:

app/main.py is the composition root.
app/common/ holds shared shell, markup, identity, and helpers.
app/features/<name>/urls.py owns Route endpoints.
app/features/<name>/handlers.py owns handler factories and register_<feature>(app, ...).
app/features/<name>/views.py turns data into HTML.
Optional data.py, models.py, signals.py, and subjects.py appear only when the feature needs them.
tests/test_<feature>.py uses TestClient against the production bootstrap.

The single-file examples, Hello world and Realtime tiles, are for learning mechanics. They are not the preferred shape for a new product.

3. Run the app

bash

uv run stario watch app.main:bootstrap

Open http://127.0.0.1:8000. For a one-shot server without reload, run uv run stario serve app.main:bootstrap. If the port is busy, set STARIO_PORT.

4. Use the examples as references

Give the agent AGENTS.md plus the closest example. Copy chat-room for layout. Tiles and hello-world teach the loop. Go-to architecture is the wire split. Add a subscribe stream only when the UI needs push.

AGENTS.md. Structuring apps.