How the agent works

When you send a request, Highwind’s agent acts like a product engineer and a designer rolled into one: it reads your project, writes the code, checks that everything works and sums up what it did. You watch the app take shape live in the preview. This page explains what happens in the meantime, and with which technology.

Your app’s technology

Every app made with Highwind is a real web project, with standard code you can read, change and download.

React and TypeScript

The interface is written in React 19 with strict TypeScript: every component is typed, and errors show up before the app goes live.

Vite

The development server that runs the live preview, and builds the published version.

Tailwind CSS v4

All styles go through Tailwind classes. Colors and fonts live in a central theme.

react-router and lucide

react-router for apps with several screens, lucide-react for icons. Both are already installed.

The agent only adds a library when it really helps (for example recharts for charts). It creates no server and no database until your app needs one: see Where data goes.

File layout

Folder or file	Contents
src/App.tsx	The root component, with the routes if the app has several screens
src/pages/	One page per screen
src/components/	Reusable components (header, cards, forms…)
src/lib/	Utilities (shared data, hooks, the cn() helper)
src/index.css	The theme: colors, fonts, animations
public/	Files served as is, including your images in public/assets/
worker/index.ts	The app’s server, only if it has one (see The app server)

You can view and edit everything in the Code tab: see The code.

How a request runs

1. The agent explores. It goes through the file list and only reads the files it needs (the “Browsing files” step in the thread). At the start of a conversation, it also gets the project’s AGENTS.md file; your project instructions come with every message.

2. It writes the code, top-down. On a new app, it first makes src/App.tsx render something real (the layout and the first screen or section), then adds the remaining sections or pages one at a time, wiring each in as soon as its file exists. The result: the preview fills up as it goes instead of staying empty until the end.

3. It never shows a broken state. It never imports a file that doesn’t exist yet: a component is written first, then used in the next step.

4. It checks. Before finishing, it runs the check tool: a TypeScript check, a production build, then a read of the errors seen by the preview in your browser (exceptions, console errors, blank page). It fixes every error and runs check again until everything passes. check also flags colors hard-coded outside the theme. In the thread, you see “Checked: typecheck, build and preview OK” or “Some errors remain to be fixed”.

5. It sums up. It ends with a short summary (2 to 4 sentences) of what it built or changed, in your language, without pasting code.

6. It suggests next steps. Below the summary come 2 or 3 suggestions specific to your app. Clicking a suggestion sends it straight to the agent.

Tip

Click Show steps under a reply to see each of the agent’s actions (files read, written, checks), and Show changes for the details of the modified code.

When the agent asks you questions

If a few answers would really change what it builds (your brand name, your real offers and prices, your contact details, a choice between clearly different directions), the agent sends you a short form instead of guessing, with its best guesses already filled in. It never asks about a detail it can decide itself, and sends at most one form per request. See Agent questions.

When your app needs to keep data and several solutions would work, it shows you a choice card: see Where data goes.

Apps with several screens get real routes

The agent shapes your app like the real product you asked for. Anything with several screens (a tool, a dashboard, a SaaS, a multi-page site) gets real routes with react-router:

• one page per screen in src/pages/, each with its own address (/projects, /settings…);
• a shared layout (header, sidebar) used by every page;
• working navigation, with the active tab highlighted;
• detail views with a parameter (/projects/:id) and a page for unknown addresses.

A simple landing page stays a single page, with sections and anchors. Once published, every address of your app opens directly, even when shared as a link.

Create an invoice tracker for freelancers: a dashboard, a list of invoices with
a detail page, a clients page and a settings page.

The sandbox

Each project runs in its own isolated environment, a sandbox, hosted in the European Union. The Vite development server is already running there: every file the agent writes shows up in the preview right away.

• A project’s sandbox has no access to any other project.
• The agent installs the packages it needs there (add_dependency) and runs its checks there.
• When you stop using it, the preview goes to sleep; it starts again when you come back to the project. Your code is saved in your versions: nothing is lost.

The project conventions (AGENTS.md)

Each project contains an AGENTS.md file describing its conventions. The agent gets it at the start of every conversation and follows it. It covers, among other things:

• the stack and the @/ alias to import from src (@/components/Header);
• where components, pages and utilities go;
• styles only as Tailwind classes, colors and fonts only through their theme roles;
• dark mode through a managed block in src/index.css;
• navigation rules (<NavLink> or <Link>, never an internal <a> link);
• the title, description and sharing tags to fill in index.html;
• the .highwind/ folder, managed by Highwind, which must not be touched.

Tip

To give the agent your own rules (tone, colors, language, things to avoid), use Instructions for the agent in the project settings instead: it rereads them on every message. See Project settings.

What the agent never does

The agent never…	Why
leaves TODOs or incomplete code	Every file it writes must work as is
uses placeholder text (lorem ipsum)	It writes realistic content that fits your request
hard-codes a color in a component	The Theme panel could no longer change the app’s look
replaces an image you provided	Your images stay in place; generated images always get a free file name
reads or edits the secrets files (.env.local, .dev.vars)	They’re managed by Highwind and hidden from the agent
asks you for an API key in the chat	It uses a secure card instead (see Secrets)
enables a database on its own	You decide, through the choice card
drops or renames a table or a column	Destructive migrations are refused, to protect the data
writes the server or database configuration	Highwind sets it up and maintains it
changes anything in Discussion mode	It answers, explains or proposes a plan without touching the app (see Discussion mode)

What the agent sees of your accounts

The agent sees the names of your project’s secrets, never their values. What it reads in your context sources (Notion, Linear, Figma, Kameleoon) is treated as reference data, never as instructions. See Context sources.

Going further: what the agent receives with your message

Besides your text, the agent receives, depending on the case:

• the art directions drawn for a new app (see Design and themes);
• the element selected in the preview, if you picked one (see Select an element);
• your project instructions;
• attached images: a reference image (screenshot, mockup) it looks at, or a project image it places in the site;
• the list of existing secrets (names only) and the backend status if it’s active;
• the context sources connected to your account.

See also

Writing good promptsThe phrasing that gives the best results.

Design and themesDesign standards and the role-based theme.

Where data goesLocal state, server or database.

VersionsEvery agent reply creates a version you can restore.