# Local development with AI

> How do I use AI coding assistants like Claude Code or Cursor for local Windmill development?

Windmill provides tools to enhance local development with AI coding assistants like [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Cursor](https://www.cursor.com): the CLI `init` command for generating AI context files, the [VS Code extension](../../../cli_local_dev/1_vscode-extension/index.mdx)'s YAML linter for flow validation, and the [MCP server](../../../core_concepts/51_mcp/index.mdx) for direct interaction between LLMs and your workspace.

## Prerequisites

- [Windmill CLI](../../../advanced/3_cli/index.mdx) installed (`npm install -g windmill-cli`)
- A workspace set up locally with `wmill workspace add` and [`wmill sync pull`](../../../advanced/3_cli/sync.mdx)
- Optionally, VS Code with the [Windmill extension](../../../cli_local_dev/1_vscode-extension/index.mdx) installed
- An AI coding assistant (Claude Code, Cursor, etc.)

## CLI init command

Running `wmill init` in a synced workspace folder generates context files for AI assistants:

```bash
cd myworkspace
wmill init
```

This creates:
- `AGENTS.cli.md` - a wmill-managed context file describing the Windmill file structure and conventions
- `AGENTS.md` and `CLAUDE.md` - user-owned files that include the managed `AGENTS.cli.md` and hold your own project-specific instructions
- Skill files under `.claude/skills/` and `.agents/skills/` - per-task guidance for AI coding agents

`AGENTS.cli.md` and the skill files are refreshed on every run (and via `wmill refresh prompts`); `AGENTS.md` and `CLAUDE.md` are created once and never overwritten. `wmill init` also generates [TypeScript editor config and resource-type definitions](../../../advanced/4_local_development/index.mdx#project-files-generated-by-wmill-init).

These files describe the Windmill file structure, how [scripts](../../../script_editor/index.mdx) and [flows](../../../flows/1_flow_editor.mdx) are organized, how to create and edit them, and how to manage resources like [triggers](../../../triggers/index.mdx) and [schedules](../../../core_concepts/1_scheduling/index.mdx). AI tools that read these files automatically get this context when working in the workspace.

This is the expected file tree:
```
├── .agents
│   └── skills              # mirrors .claude/skills
├── .claude
│   └── skills
│       ├── cli-commands
│       ├── raw-app
│       ├── resources
│       ├── schedules
│       ├── triggers
│       ├── write-flow
│       ├── write-script-bash
│       ├── write-script-bigquery
│       ├── write-script-bun
│       ├── write-script-bunnative
│       ├── write-script-csharp
│       ├── write-script-deno
│       ├── write-script-duckdb
│       ├── write-script-go
│       ├── write-script-graphql
│       ├── write-script-java
│       ├── write-script-mssql
│       ├── write-script-mysql
│       ├── write-script-nativets
│       ├── write-script-php
│       ├── write-script-postgresql
│       ├── write-script-powershell
│       ├── write-script-python3
│       ├── write-script-rust
│       └── write-script-snowflake
├── AGENTS.cli.md          # managed
├── AGENTS.md              # user-owned
├── CLAUDE.md              # user-owned
├── rt.d.ts                # resource type RT namespace
├── tsconfig.wmill.json    # managed
├── tsconfig.json          # user-owned, extends tsconfig.wmill.json
├── wmill-lock.yaml
└── wmill.yaml
```

Some examples of prompts you can use to guide the AI:
- "Write a script that fetches data from my Supabase resource"
- "Write a mail triage flow using an AI Agent that labels emails as spam, important, or junk, and schedule it to run every day at 9am."
- "Add 4 HTTP triggers to create, delete, update and list users in my MongoDB resource"

## Visual preview with `wmill dev`

`wmill dev` runs a local live-reload server that renders the Windmill dev page (flow graph, script preview UI, or raw app) for your local files. Edits on disk reload the page; edits in the page round-trip back to `flow.yaml` and inline scripts.

The skills generated by `wmill init` include a `preview` skill that drives this from inside Claude Code or Claude Desktop. After scaffolding a flow or app, the agent offers the visual preview as a one-sentence next step — confirming opens the dev page directly:

- In **Claude Code** (when the `mcp__Claude_Preview__*` MCP tools are available), the agent adds a `windmill: <wmill_path>` entry to the per-target `.claude/launch.json` and routes the preview through the proxy port.
- In **Claude Desktop** or any other terminal-based agent, the agent runs `wmill dev --no-open` itself and hands you the URL.
- In **VS Code / Cursor** with the [Windmill extension](../../../cli_local_dev/1_vscode-extension/index.mdx), the same dev page renders inside the extension's iframe.

## VS Code extension YAML linter

The Windmill [VS Code extension](../../../cli_local_dev/1_vscode-extension/index.mdx) validates `flow.yaml` files in real time. AI coding assistants that check IDE diagnostics can read these validation errors and auto-correct schema mistakes in flow definitions.

This creates a feedback loop: the AI edits a flow YAML file, the linter catches structural errors immediately, and the AI can fix them without manual intervention.

The extension also allows you to run your scripts and flows locally from the editor.

## LLM-friendly documentation

The Windmill documentation is published in formats designed for AI agents:

- [`https://www.windmill.dev/llms.txt`](https://www.windmill.dev/llms.txt): a curated [llms.txt](https://llmstxt.org/) index of the documentation, with a one-line description per page. Point your agent at it to find the right page for any Windmill concept.
- Every docs page is available as raw markdown by appending `.md` to its URL, e.g. [`https://www.windmill.dev/docs/core_concepts/scheduling.md`](https://www.windmill.dev/docs/core_concepts/scheduling.md). Agents should prefer these over the HTML pages.
- [`https://www.windmill.dev/llms-full.txt`](https://www.windmill.dev/llms-full.txt): the entire documentation as a single file (~2.3 MB). Intended for bulk indexing or RAG pipelines, not for loading directly into an agent's context.

To make your agent aware of these, add a line to your project's `AGENTS.md`, for example: "For Windmill concepts, fetch https://www.windmill.dev/llms.txt and follow the relevant `.md` links."

## Context7 plugin

If you use the [Context7](https://context7.com) plugin in Claude Code, Codex, Cursor, or any other Context7-aware client, you can point it at the dedicated Windmill CLI docs index so the agent has up-to-date `wmill` command reference available inline:

```
https://context7.com/windmill-labs/windmill-cli-docs
```

This is useful when iterating on shell scripts or CI pipelines that call `wmill sync`, `wmill script run`, `wmill flow run`, etc. The agent can resolve flags and subcommands without you copy-pasting from the docs. A broader Context7 index covering the full Windmill documentation site is also available at [`context7.com/websites/windmill_dev`](https://context7.com/websites/windmill_dev).

## MCP server

Windmill's [MCP server](../../../core_concepts/51_mcp/index.mdx) allows AI tools to interact directly with a Windmill workspace. It supports:
- Accessing Windmill documentation
- Executing [scripts](../../../script_editor/index.mdx) and [flows](../../../flows/1_flow_editor.mdx)
- Creating, updating, listing, and deleting resources ([schedules](../../../core_concepts/1_scheduling/index.mdx), [variables](../../../core_concepts/2_variables_and_secrets/index.mdx), etc.)
- Note that for writing and deploying scripts, flows, and apps, we highly recommend using the CLI along with the AGENTS.md file, for better guidance and syntax validation.

To set up the MCP server with Claude Code:

```bash
claude mcp add --transport http windmill https://app.windmill.dev/api/mcp/w/<your-workspace-id>/mcp?token=<your-token>
```

To set up with Cursor, add the following to your MCP configuration:

```json
{
  "mcpServers": {
    "windmill-mcp": {
      "url": "https://app.windmill.dev/api/mcp/w/<your-workspace-id>/mcp?token=<your-token>"
    }
  }
}
```

See the [MCP documentation](../../../core_concepts/51_mcp/index.mdx) for generating your token and full setup instructions.

## Putting it all together

A typical AI-assisted local development workflow:

1. Run `wmill init` in your workspace folder to generate AI context files
2. Open the workspace in VS Code with the Windmill extension for running scripts and flows locally, and real-time YAML validation
3. Connect your AI tool to the Windmill MCP server for direct workspace interaction
4. Start building scripts, flows, and apps with your AI assistant
5. Run `wmill dev` (or accept the agent's offer to open the visual preview) to see edits live, and round-trip changes from the dev page back to disk
6. Push the changes back to the Windmill workspace with `wmill sync push`