Instructions for coding agents to set up a new Hyperflask project on behalf of the user. Human readable documentation is available at https://hyperflask.dev.
Hyperflask is a batteries-included full stack web framework built on Flask. It is optimized for containerized, component-driven, HTMX-based web apps.
New projects are created using Hyperflask-Start, the official starter kit. Development happens inside a dev container: Python is not needed on the host machine.
Follow these steps in order. Do not skip the requirement checks.
Required:
- A UNIX like system: Linux, macOS or WSL on Windows. On Windows, run all commands from inside WSL.
- Docker, with the daemon running. Check with
docker info.
To work in the dev container, one of:
- VS Code with the Dev Containers extension (recommended). Check with
code --list-extensions | grep ms-vscode-remote.remote-containers. - devcontainers-cli, to use dev containers from a terminal without VS Code. Check with
devcontainer --version.
If Docker is missing or not running, stop and ask the user to install or start it. Do not install system software without the user's consent.
Without Docker, Hyperflask can still run directly on the host if it has Python >= 3.11, uv and nodejs >= 24. This is not the recommended setup: mention it to the user and only use it if they agree.
Ask the user for:
- Project name: for example
My Hyperflask App. The project folder is derived from it: lowercased, with spaces, dashes and dots replaced by underscores (my_hyperflask_app). - Coding agent to install in the dev container:
claude(Claude Code),codex(OpenAI Codex),opencode(OpenCode) ornone. Default to the agent you are. - Parent directory where the project folder will be created. Default to the current directory.
Make sure the project folder does not already exist.
Run the official start.sh script from the parent directory. Provide the options using the HYPERFLASK_PROJECT_NAME and HYPERFLASK_AGENT environment variables so that it runs without prompting:
curl -L https://start.hyperflask.dev | HYPERFLASK_PROJECT_NAME="My Hyperflask App" HYPERFLASK_AGENT=claude bashThis runs in a docker container using the same image as the dev container. It generates the project with cruft, creates a .env file with a secret key and installs the agent skills (including the hyperflask skill).
If the host already has uv and nodejs, the same can be done without Docker:
uvx cruft create --no-input --extra-context '{"project_name": "My Hyperflask App", "agent": "claude"}' https://github.com/hyperflask/hyperflask-startThen initialize a git repository in the project folder and make a first commit (git init && git add . && git commit -m "Initial commit"). This is required to later update the project from the template using uvx cruft update.
The dev container must be opened by the user:
- Open the project folder in VS Code (
code <project_folder>). - Accept the "Reopen in Container" prompt, or run the "Dev Containers: Reopen in Container" command from the Command Palette.
- Wait for the container to build. Dependencies are installed automatically.
- In a VS Code terminal, start the development server:
uv run hyperflask dev
From the project folder:
- Start the dev container:
devcontainer up --workspace-folder . - Start the development server:
devcontainer exec --workspace-folder . uv run hyperflask dev
The coding agent selected in step 2 is installed in the dev container and authenticated using the user's credentials from the host. It can be launched with devcontainer exec --workspace-folder . claude (or codex, opencode).
From the project folder:
uv syncnpm installuv run hyperflask dev
The development server listens on http://localhost:5000 with auto-reload enabled. Check that the home page loads.
Emails sent in development are caught by Mailpit, available at http://localhost:8025 when using the dev container.
Tell the user the project is ready and summarize:
- Where the project is and how to start the development server.
- That the project contains an
AGENTS.mdfile which they should complete with a description of their project. - That the coding agent is available inside the dev container.
To build the app, use the hyperflask skill installed in the project. It contains the full documentation. If it is missing, install it with npx skills add https://hyperflask.dev --skill hyperflask.
Useful links:
- Documentation: https://hyperflask.dev
- Getting started tutorial: https://hyperflask.dev/getting-started/
- Documentation for LLMs: https://hyperflask.dev/llms.txt and https://hyperflask.dev/llms-full.txt