AI Agents and Editors
claude mcp add wisp -- wisp mcp # Claude Code
wisp update-docs # refresh AGENTS.md and wisp-ref/ to the installed Wisp
AI Agents
Every app gets an AGENTS.md, the core of the reference, plus a pointer file for each agent that reads its own (CLAUDE.md, .github/copilot-instructions.md, .cursor/rules/wisp.mdc). The core holds Files, A page, Actions, Templates, Components, Endpoints and Gotchas. Its index names the topic files in wisp-ref/ and when to read each one: content.md, nojs.md, browser.md, members.md, hooks.md, api.md and commands.md. Your own notes go after the last line of each file. wisp update-docs updates the rest, keeps your notes and writes any missing pointer file. It also writes a pointer file again when it holds, byte for byte, the text that an older wisp new wrote. It writes no other file of wisp-ref/.
llms.txt (llmstxt.org) links the docs. llms-full.txt is AGENTS.md, the topic files and the docs pages in one file.
wisp mcp
A Model Context Protocol server over stdio for the app in the current folder:
| Tool | Answers |
|---|---|
wisp_docs(topic) | the docs sections about the topic, or a list with no topic |
wisp_check() | {"ok":true} or {"ok":false,"errors":[{file,line,col,code,message}]} |
wisp_route_list() | each route's pattern, folder, params, page, actions and endpoints |
wisp_component_list() | each component's name, file and props |
wisp_route_add(path, kind) | writes +page.wisp (default), +layout.wisp, +error.wisp or +server.rs, never overwriting |
Setup, in the app's folder:
- Claude Code:
claude mcp add wisp -- wisp mcp - Cursor:
.cursor/mcp.jsonwith{"mcpServers":{"wisp":{"command":"wisp","args":["mcp"]}}} - VS Code:
code --add-mcp '{"name":"wisp","command":"wisp","args":["mcp"]}', or.vscode/mcp.jsonwith{"servers":{"wisp":{"type":"stdio","command":"wisp","args":["mcp"]}}}
wisp lsp
wisp lsp gives you highlighting, completion, hover docs, errors and formatting in .wisp files. Install the VS Code extension, or see the setup for Neovim, Helix, Zed, JetBrains, Sublime Text or Emacs below.
| Feature | What it does |
|---|---|
| Problems | Checks the buffer as you type and the whole app on open and save, as wisp check does. Each problem of a file shows, up to 100. A parse error does not stop the parse: the parse continues at the next tag or block tag, so a file shows each parse error, up to 100. A later parse error may be a result of an earlier one. The build stops at the first parse error. The one problem that wisp check finds in the app shows in the file that it names, with the problems of the buffer. After a change, the problem read from the disk is stale, so the file hides it until the next save. A closed file keeps the problem in the Problems list. A component file with a problem does not hide the other components. A use of it says "component Bad has an error". A .wisp page that the sitemap lists also gets the seo-title, seo-description and seo-h1 warnings of the build |
| Hover | Docs for {@props}, directives, blocks, route params, the const knobs (CACHE, RATE_LIMIT, SSR, ...), <form fields>, action="?/x", use:enhance, component CSS custom properties (<Card --color="red">), data-wisp-* attributes, <wisp:...> elements, filters and loop.*. Also Rust attributes in a block: #[action], #[model], #[validate(..)] and each rule, #[derive(Rest)], #[rest(..)], #[json(..)], #[unique]. Any Wisp item (cx.x, Type::x, wisp::x) shows its signature and /// docs, and rust-analyzer shows the same in .rs files |
| Go to definition | <Card> to its file (a library's <ui:Button> too), '$lib/x.js' to src/lib/x.js, a literal href="/x/" to the route's file. That is the Markdown file of a Markdown route. A matcher int fits only digits that fit a u64. action="?/save" goes to #[action] fn save of the route |
| Find references | Each <Card> tag in the .wisp files of the app and the file of the component. Each use of an app fn in .wisp and .rs files. For a form action: its fn and each ?/save of the route |
| Rename | A component (its tags and its file). A prop (its {@props} entry, its uses in the component, and title=, bind:title and the shorthand ${title} on each tag). A name that a block head declares ({#each .. as item}, {:then x}, {@const x}, {#snippet} parameters, {#if let}), only in its block. A form action (its fn and each ?/save of the route). The rules are under the table |
| Outline | The --- block, <script>, <style>, components, <wisp:...> elements and {#...} blocks, nested as in the file. Editors show it as the outline and the breadcrumbs |
| Linked editing | A change to the name of an open tag changes the name of its close tag, and the reverse |
| Signature help | The props of a component in its open tag, and the parameters of an app fn in a call |
| Completion | Components and their props, directives, on: events and modifiers, {#...} blocks, route paths in href, #[ attributes. In ${...} and in a block head ({#if ...}): the names of the template in scope ({#each}, {#if let}, {:then}, {#snippet} args, {@const}, {@props}), route params, cx. methods, wisp items and the items of app modules (site::slug). A field after . of another value gets no completion |
| Quick fixes | A problem with "did you mean" changes the name to the one it names. "no component Name" creates src/components/Name.wisp, when the editor can create files. A component name that is near one component changes in each tag of the file. "<Card> needs title" adds title="", title=${false}, title=${0} or title=${0.0} by the type of the prop. The prop goes in only when the line has one tag of that name. "<Card> has no prop titl" changes the name to the one prop that it is near. A missing <title>, <h1> or <meta name="description"> gets the tag at the start of the markup. The kind source.fixAll applies the first fix of each problem that has a sure fix, in one edit. It skips a fix that adds a tag or a prop with an empty value. It drops a whole fix when one of its edits touches an earlier fix. The editor offers the action for two fixes or more, and counts a fix with two edits as one |
| Formatting | the same as wisp fmt |
| Semantic tokens | Colors each word of a template by its meaning, with the standard LSP token types. See the next table |
| Colors | Shows a swatch for each CSS color and opens a color picker. It reads <style> text, style="..." values and --name="..." props. It knows hex, rgb(), rgba(), hsl() and hsla(). In <style> text and style="..." values, it also knows the named colors (red, transparent) after a :. A color in any function except url() counts, so local(red) gets a swatch too. The picker writes hex, rgb() or hsl() |
| Folding | Folds the --- block, <script> and <style>, comments, elements on more than one line, and blocks. Each branch of a block ({:else}, {:then}) folds too. A file over 1 MB gets no folds |
| Highlights | Marks the other uses of the name under the cursor in the same file: a component tag, a prop, or a name that a block head declares. It reads only the open file |
| Selection ranges | Grows the selection from the word to the hole, the attribute, the tag, the element, the block and the file. In a file over 1 MB, the selection ranges are only the word and the file |
| Inlay hints | Shows the type of each prop on a component tag, from the {@props} of the component: <Card title: &str="Hi">. Library tags such as <ui:Button> get hints too |
Rename rules:
- A rename to
cxstops, because generated code usescxin a block body. - Rename of a component, prop or block name changes no
.rsfile, no---block and no<script>. It skips fields, calls and strings. - A shorthand attribute
<a ${href}>meanshref=${href}. A rename ofhrefwriteshref=${url}and keeps the attribute name. A hole after an equal sign (href = ${url}) is a value, not a shorthand. - A form action rename stops in three cases:
- The name is a word in the Rust code beyond the
fn. - The new name is already a word there.
- Another file of the app has
?/save, or a form of the route posts with a full path (action="/todos?/save").
- The name is a word in the Rust code beyond the
- A component rename stops when the name is also in a string, the
---block, a script, a style or an attribute value (of="Card"). In a.rsfile, a name in a string counts, also when the string spans many lines. A name in a comment or a char literal does not count. - A word between
{or,and,or}that is more than 256 characters into a hole counts as a possible field. Highlights and references leave it out, and a rename stops. - The clash check reads only the route files, so a name from a glob import or a parent module is not checked.
- A browser text hole (
{:count}) does not end the block of a name. Only{:else},{:then},{:catch},{:await}and{:case}start a branch. - A prop rename stops when a tag of the component in any page already has the new name, because the build rejects a prop twice.
- The server rejects a new name that is not valid or is in use. It also rejects a rename when it cannot read each file of the app, or when a link to a folder is under
src. The server does not follow such a link. - A component rename needs an editor that can rename files.
Semantic Tokens
The grammar colors the syntax. wisp lsp then sends semantic tokens, so each word gets the color of what it is. The server reads the template text only. It does not use rust-analyzer. A page's --- block, <script> and <style> get no tokens, so the Rust and JS grammars color them. A hole ends at its closing brace as the build reads it: a } in a /* */ comment or in a raw string (r#".."#) does not end it. The block {@json data} gets tokens in a script that the browser does not run, such as <script type="application/ld+json">. The server stops after 50,000 tokens, so a very large file gets colors only in its first part.
| Construct | Example | Token type (modifiers) |
|---|---|---|
Block keywords and their } | {#each, {:else, {/if, {@const, as, let | keyword |
| New binding | k in {#each xs as k}, p in {#if let Some(p) = me}, n in {@const n = 1} | variable (declaration) |
| Use of a value | me, k | variable |
Path segment before :: | site in site::dir_of, Kind in Kind::A | namespace, type |
| Constant | KINDS | variable (readonly) |
| Function or method | dir_of, .map(..) | function, method |
| Field | .dir | property |
| Closure parameter | k in |k| k.dir | parameter (declaration at the bars) |
| Enum value | Some, None, Ok, Err (defaultLibrary), Kind::A | enumMember |
| Wisp attribute | active, fields, action, use:enhance, data-wisp-* | decorator |
| Directive | class:entry: class is keyword, entry is class | keyword + name |
| Directive modifier | .prevent and |once in on:click.prevent|once | operator (the separator), keyword |
| Browser block | {:#if, {:expr, {:/if, and the branches of a browser block ({:catch of {:#try}). A branch of a Rust block, such as {:else, is not | keyword (client) |
| Form action | save in action="?/save" | function (action) |
| Loop | loop and index in ${loop.index} | variable, property (readonly, defaultLibrary) |
| Component and its props | <Card title=..>, <ui:Card> | class, parameter |
| Wisp element | <wisp:head> | macro (defaultLibrary) |
| Filter | upper in ${name | upper} | function (defaultLibrary) |
| Hole | ${ and } | operator |
{#snippet} and {@props} | row in {#snippet row(item: &Item)}, item | function, parameter (declaration) |
Editors
Install the VS Code Extension
The extension is not published yet. The pre-release is self-hosted because GitHub suspended our account. It goes on the VS Code Marketplace and Open VSX with the full release. Until then, see Downloads for every editor package, or build it from the repository and install the file. It needs wisp on your PATH.
cd editors/vscode && npx @vscode/vsce package && code --install-extension wisp-*.vsix
VS Code
editors/vscode highlights every construct:
- The
---block and${...}holes are Rust, with Wisp's own names (cx, the framework's types,#[action],#[validate(..)],wisp::main!,loop.*) marked on top. - The template syntax: filters, spread
${...attrs}, every{#...},{@...},{:...}block and{~ ~}trim, directives (on:,class:,style:,use:),fields,action,data-wisp-*, components and their CSS custom properties (--color="red"),<wisp:...>elements, fragments<>...</>and kept comments<!--! -->. - JavaScript in
<script>, directive values,{:...}and{@attach ...}. TypeScript in<script lang="ts">. JSON in<script type="application/ld+json">,application/jsonandimportmap. A{@json expr}body there is highlighted as a tag with Rust inside (TextMate, tree-sitter: Neovim, Helix, Zed). CSS in<style>. - Runes (
$state,$derived.by,$effect.pre,$props.id,$bindable,$inspect,untrack) and$storereads such as$cart, but not inside strings or comments. Any$namecounts as a store, so jQuery-style$elis marked too. Sublime, Helix and Zed cannot extend the injected JavaScript, so runes stay plain there. - Each Wisp construct has a scope that the built-in themes color apart from the plain thing beside it. Wisp attributes (
action,fields,confirm,data-wisp-*) and the rules of#[validate(..)]look like functions, not liketitleorhref. The name ofuse:enhanceortransition:fadeis a function name, and the:of a directive takes the color of its prefix. The name inaction="?/save"is a function name.<wisp:head>is a keyword, a component is a class, and a browser block ({:#if}) differs from a Rust block ({#if}). A$storeread andloop.indexare language variables. The testnpm testof the extension checks the colors in Dark+, Light+ and Monokai. - Each kind of block, tag and directive has its own scope beside the generic one, as in the tree-sitter grammar:
{#if}and{#match}are conditional,{#each}is a loop,{#await}is try and catch,{#snippet}is a function,{@html},{@json}and{@render}are macros,{@flash},{@pager}and{@element}are built-in functions, and{@debug}is a debug keyword.bind:,class:andstyle:,use:and the motion directives (transition:,in:,out:,animate:) each have a kind scope, and.preventis a built-in constant. VS Code, JetBrains and Sublime use these scopes. - Semantic tokens of
wisp lspuse two modifiers of Wisp,clientandaction. The extension maps them to the same scopes (semanticTokenScopes) and turns on semantic highlighting for.wispfiles. - Directive modifiers (
on:click.prevent.debounce.300ms,transition:fly|local) and:global(x)in<style>. - In holes and block heads: fields (
k.dir), closure parameters (|k| k.dir) and a function named by its path (site::dir_of). Holes inside quoted attribute values (href="/${k.dir}") get the same colors. - The names a block creates get the binding scope:
as kandas (a, b), iof{#each},pin{#if let Some(p) = x}and{:case Ok(p)},{:then v},{:catch e},{@const n = ...}and the parameters of{#snippet row(a, b)}. Sublime marksas,{:then},{:catch},{@const}and{#snippet}names only. - The tree-sitter grammar (Neovim, Helix, Zed, Emacs) parses the same names as their own nodes:
(binding)is@variable.parameter,(snippet_name)is@function. Sokin{#each xs as k}is a name, not a Rust type.
The grammars are generated from tables in editors/vscode/syntaxes/gen.js. The test editors_cover_the_syntax fails when a block, directive, attribute, filter, <wisp:...> element or macro from wisp lsp has no scope or snippet.
The extension also has snippets (every block, tag and directive, plus page, page-rs, parent-load, trailing-slash, layout, template, component, action and form-fields), folding, indentation and format on save. Its commands are Wisp: Start dev server, Check the app, Build for release, List routes, New route... (also on a routes/ folder in the Explorer), Restart language server and Show language server output. The extension writes the close tag after you type the > of a start tag in markup (wisp.autoCloseTags, on by default). It skips void and self-closing tags, and < in the --- block, holes, block heads, comments, <script> and <style>. It also sets emmet.includeLanguages to treat wisp as html, so Emmet works in .wisp files. The Neovim, Helix, Zed, JetBrains and Emacs packages do not close tags or set up Emmet. wisp.path is a user-only setting, so a project cannot choose the program the editor runs. editors/prettier-plugin-wisp formats through wisp fmt --stdin.
editors/tree-sitter-wisp is a tree-sitter grammar with the same embedding through injections. Neovim, Helix and Zed use it. It marks a component's tag (a library's <ui:Button> too) as @type and an element's tag as @tag. Each kind of block has its own capture. {#if} and {:else} are @keyword.conditional, and {#each} is @keyword.repeat. {#await}, {:then} and {:catch} are @keyword.exception, and {#snippet} is @keyword.function. The tags {@html}, {@json} and {@render} are @function.macro. {@const} and {@id} are @keyword, and {@debug} is @keyword.debug. A directive is a (directive_prefix) and a (directive_target). The prefix on: is @keyword.directive and bind: is @keyword.operator. The prefixes class: and style: are @keyword.modifier, and use: is @function.macro. The prefixes transition:, in:, out: and animate: are @keyword.coroutine. Modifiers such as .prevent are @constant.builtin. An inline style="..." is CSS and an onclick="..." (any event handler attribute of the HTML standard, such as onpaste or onplay) is JavaScript. Helix uses its own scope names for these (keyword.control.conditional), and your theme decides the colors. editors/README.md has each setup in full.
Neovim
editors/nvim is a plugin: the wisp filetype, the tree-sitter parser for nvim-treesitter, queries, wisp lsp through vim.lsp.config (Neovim 0.11+) or nvim-lspconfig, and LuaSnip snippets. With lazy.nvim:
{
url = 'https://code.wispweb.dev/wispdev/wisp.git',
ft = 'wisp',
init = function(plugin)
vim.opt.rtp:append(plugin.dir .. '/editors/nvim')
vim.filetype.add({ extension = { wisp = 'wisp' } })
end,
dependencies = { 'nvim-treesitter/nvim-treesitter' },
config = function() require('wisp').setup({ format_on_save = true }) end,
}
Then :TSInstall wisp rust javascript typescript css. editors/nvim/README.md has the options and a setup without a plugin manager.
Helix
Merge editors/helix/languages.toml into ~/.config/helix/languages.toml, then:
hx --grammar fetch && hx --grammar build
mkdir -p ~/.config/helix/runtime/queries/wisp
cp editors/helix/queries/wisp/*.scm ~/.config/helix/runtime/queries/wisp/
hx --health wisp
Zed
Install editors/zed with zed: install dev extension. It registers .wisp with the grammar, highlights, outline and wisp lsp (wisp must be on PATH). Zed formats on save by default.
JetBrains
For RustRover, IntelliJ IDEA, WebStorm and the rest: Settings → Editor → TextMate Bundles → +, then pick editors/vscode for highlighting. For wisp lsp, install the free LSP4IJ plugin. Under Settings → Languages & Frameworks → Language Servers, import editors/jetbrains/lsp4ij-template, or add a server with command wisp lsp and file pattern *.wisp. editors/jetbrains/README.md also shows the native LSP API of the paid IDEs.
Sublime Text
editors/sublime is a package for Sublime Text 4 with Wisp.sublime-syntax, WispRust.sublime-syntax, completions and the client entry for the LSP package. Copy the folder into Preferences → Browse Packages… as Wisp, install LSP, and paste:
{ "clients": { "wisp": { "enabled": true, "command": ["wisp", "lsp"], "selector": "text.html.wisp" } } }
Emacs
editors/emacs/wisp-ts-mode.el is a tree-sitter major mode (Emacs 29.1+) with highlighting, indentation, imenu, <!-- --> comments and wisp lsp through eglot.
(add-to-list 'load-path "~/src/wisp/editors/emacs")
(require 'wisp-ts-mode)
(add-to-list 'treesit-language-source-alist
'(wisp "https://code.wispweb.dev/wispdev/wisp" "7d546c0949ed3e5a958a39902817c4af45aa9947" "editors/tree-sitter-wisp/src"))
;; once: M-x treesit-install-language-grammar RET wisp RET
(add-hook 'wisp-ts-mode-hook #'eglot-ensure)
File Kinds
The above covers .wisp files (+page.wisp, +layout.wisp, +template.wisp, +error.wisp, +loading.wisp, +default.wisp, components). +page.rs, +server.rs and hooks.rs are Rust, so your editor's Rust support applies. editors/snippets/rust.json adds snippets for #[action], #[model], #[remote], fn load, fn load(parent: &Parent), const TRAILING_SLASH and endpoints.
Is This Page Useful?