ArtScript is built to be written by models. This guide is about getting the most out of that: what to give the agent, which tools to connect, and the habits that keep each change cheap.

What the agent should read #

The spec is the same in every request, so with prompt caching it is billed at the cache rate after the first one. The measured runs counted it in full anyway.

Agents that crawl the web can start from llms.txt or read everything at once in llms-full.txt. Every page of this site has a Markdown version and a "Copy page for your AI" button.

Instructions file #

art init writes AGENTS.md and CLAUDE.md into each project. Agents that read instruction files (Claude Code, Cursor, Codex, Windsurf...) pick it up by themselves. It tells them to:

• read ARTSCRIPT.md before writing code, or ARTSCRIPT-EDIT.md to only change it;
• check every change with npx art check --ai;
• read npx art context instead of whole files;
• prefer a small art patch to rewriting files;
• write test blocks and run npx art test.

Cursor also gets .cursor/rules/artscript.mdc, a rule attached to every .art file. If your agent uses another file (.github/copilot-instructions.md, .windsurfrules), copy the same text there.

MCP #

art mcp is an MCP server (stdio) with four tools:

• art_spec: the spec, full or the short edit version.
• art_check: typecheck; errors as JSON with expected, actual and fixes.
• art_context: the project map, or the source and patch paths of the named parts.
• art_patch: apply a patch; atomic and typechecked, nothing is written if it fails.

Claude Code:

claude mcp add artscript -- npx art mcp

Cursor (.cursor/mcp.json), Windsurf and other clients:

{
  "mcpServers": {
    "artscript": { "command": "npx", "args": ["art", "mcp"] }
  }
}

Use --dir path when the project isn't the working directory.

Errors that carry their fix #

$ npx art check --ai
{"code":"E1011","type":"UNKNOWN_FIELD","loc":"src/app.art:13:10","at":"Users","expr":"u.emial","expected":"id|name|email","fixes":["email"]}

Each error is one JSON line: a stable code and type, where it is, the expression, what was expected, what was found and the suggested fixes. The model doesn't need to guess, and the retry is usually a one-line patch. The catalog is in Errors.

The compiler is also tolerant of what models write out of habit when it's unambiguous (TypeScript-style function types, props without commas, a one-line if), and canonical formatting (art fmt) cleans it up afterwards.

Patches instead of rewrites #

To change existing code, the agent sends only the change:

replace Todos/column/title
  title "My tasks"
insert after Todos/column/row
  text "Type and press Enter" muted
set Todos/column gap=6

Paths come from art context: Component/tag/tag[n] for the view, Component.member for members, Model.field for fields. The whole patch is checked and applied atomically, so a broken edit never lands half-way. The format is in the edit spec.

A workflow that stays cheap #

1. Start from the spec, and a template if one is close (art init app --template users).
2. One feature per request. Small requests mean small answers and small retries.
3. Check after every change (art check --ai) and feed the errors back as they are.
4. Write tests for the flows that matter, and run them after each change.
5. For later changes, give the edit spec and art context of the parts involved, and ask for a patch.

Prompts that work #

For a new app:

Build a [description] in ArtScript. The spec is in ARTSCRIPT.md.
Put it in src/app.art. Run `npx art check --ai` and fix every error.
Add test blocks for the main flows and make `npx art test` pass.

For a change:

In the ArtScript app, [change]. Read ARTSCRIPT-EDIT.md and
`npx art context [Component]`, answer with an art patch, apply it
with `npx art patch`, then run `npx art check --ai` and `npx art test`.

What it costs #

The benchmarks compare ArtScript with React, Svelte, Vue and SolidJS on the same tasks, with Claude Opus, Sonnet and Haiku, counting the spec, retries and thinking tokens. Over 50 tasks, ArtScript cost 50% less per working result than React with TypeScript with Sonnet, 45% less with Opus and 40% less with Haiku.