For AI

ArtScript for AI agents

ArtScript is designed around one number: what it costs a model to build an app and to keep changing it. This page is what you give your agent, and what it can read by itself.
One promptPaste it into Claude Code, Cursor, Codex or any agent: it creates the project, registers the MCP server, points the model at the spec and sets the check-fix loop. Then add what you want built.
Read it
llms.txtThe entry point for AI crawlers and agents: what ArtScript is and where each document is.
Core spec · ~1900 tokensThe structure of the language with a whole app as the example. Measured on the 50 tasks: the same results and cost as the full spec; on a canvas app, with the project rule for heavy code, cheaper. Enough for a small app.
MarkdownRead it
Full spec · ~3900 tokensThe whole language: declarations, state, the backend, the view, tests and the rules the compiler checks. Give it before the first line of code.
MarkdownRead it
Edit spec · ~700 tokensEnough to change existing code: the code the agent reads already shows the syntax. Use it for every task after the first one.
Markdown
Every page as MarkdownEach guide has a Markdown version and a button that copies it for your AI. Every page is also prerendered HTML, readable without JavaScript.

Connect the tools (MCP)

art mcp is an MCP server over stdio. In a project created with art init:
sh
claude mcp add artscript -- npx art mcp
Cursor, Windsurf and other MCP clients take the same command in their config:
json
{
  "mcpServers": {
    "artscript": { "command": "npx", "args": ["art", "mcp"] }
  }
}
ToolWhat it does
art_specThe language spec (full, or the short edit version).
art_checkTypechecks the project; errors as JSON with expected, actual and fixes.
art_contextThe project map, or a component's source with every patch path.
art_patchApplies a structured edit: atomic and typechecked, nothing is written on error.

The prompt

Everything an agent needs to start, in one paste. It is the same loop the instructions file describes, for agents that don't have the project yet.
markdown
Build this with ArtScript (https://artscript.dev), a full-stack web language designed for AI agents.

Setup (skip what already exists):
1. `npm create artscript@latest my-app && cd my-app && npm install`
2. If you support MCP, register the server: `claude mcp add artscript -- npx art mcp` (Claude Code) or add {"command":"npx","args":["art","mcp"]} to your MCP config. It gives you art_spec, art_check, art_context and art_patch as tools.

Before writing any .art code, read the language spec once: ARTSCRIPT.md in the project (or https://artscript.dev/md/SPEC.md, ~3.4K tokens); for a small app or a canvas one, ARTSCRIPT-CORE.md (https://artscript.dev/md/SPEC-CORE.md, ~1.9K tokens, a whole app as the example) is enough. To change existing code, ARTSCRIPT-EDIT.md (~800 tokens) is enough.

How to work:
- Expressions are JavaScript; only the structure (page, component, model, api, state, computed, data, fn, the view) is ArtScript's own.
- Write everything in `.art`: data, constants, helpers and formatting (`Intl`, `Date` and string methods cover most of it); when you do need an npm package, call it from `.art` too (`use "pkg" { x }`). Imperative code goes in a `.ts` file instead: code that drives the DOM or a canvas, or runs heavy loops (an animation or physics loop, canvas or WebGL drawing, a parser), and the wrapper of a library that owns its DOM (a map, a chart). Not in `.ts`: mock data, constants, date or money formatters, small wrappers around npm functions. What you import from `.ts` arrives as `Any`: the checker can't verify it, and `art check` warns (`MODULE_COULD_BE_ART`) when a module could be ArtScript.
- After every change run `npx art check --ai`: one JSON line per error, each with expected, actual and fixes. Apply the fix; don't guess.
- Read `npx art context <Component>` instead of whole files; prefer a small `npx art patch` over rewriting files.
- Split the code into files from the start: every `.art` file in `src/` (subfolders too) is part of one program, with no imports. `app.art` keeps the pages, each putting its sections together; one component per file in `src/components/`; the data and constants people change (prices, texts, an email address) in `src/config.art`; the tests in `src/tests.art`. A one-screen app can stay in `app.art`.
- Write test "..." { } blocks for the main flows and run `npx art test`.
- Format with `npx art fmt --write`, run with `npm run dev`, ship with `npx art build`.

Now: 

The instructions file

art init writes this AGENTS.md (and the same CLAUDE.md) into every new project, next to ARTSCRIPT.md and ARTSCRIPT-EDIT.md. Agents that read instruction files follow it without being told.
markdown
# Instructions for AI agents

<!-- artscript:start: kept up to date by `npx art upgrade`; write your own instructions after the end marker -->
This project uses **ArtScript** (`.art` files in `src/`). Read `ARTSCRIPT.md` (the whole language, ~3.4K tokens) before writing code; `ARTSCRIPT-CORE.md` (~1.9K tokens, a whole app as the example) is enough for a small app or a canvas one. To only change existing code, `ARTSCRIPT-EDIT.md` (~800 tokens) is enough.

If your tool supports MCP, `npx art mcp` gives you `art_spec`, `art_check`, `art_context` and `art_patch` as tools.

- Check every change with `npx art check --ai`: it returns errors as JSON with suggested `fixes`.
- To understand a part without reading everything: `npx art context` (project map) or `npx art context <Component>`.
- Split the code into files from the start: every `.art` file in `src/` (subfolders too) is part of one program, with no imports. `app.art` keeps the pages, each putting its sections together; one component per file in `src/components/`; the data and constants people change (prices, texts, an email address) in `src/config.art`; the tests in `src/tests.art`. A one-screen app can stay in `app.art`.
- To change existing code, prefer a small `art patch` (see the spec) over rewriting files: `npx art patch <file.patch>`.
- Canonical format: `npx art fmt --write`.
- Ready-made components (as source): `npx art add DataTable Pagination ConfirmButton SearchBox Stat EmptyState`.
- Behavior: write `test "..." { ... }` blocks (see the spec) and run `npx art test`.
- Expressions are JavaScript; only the structure (`page`, `component`, `model`, `api`, `state`, `computed`, `data`, `fn`, the view) is ArtScript's own.
- Write everything in `.art`: data, constants, helpers and formatting (`Intl`, `Date` and string methods cover most of it); when you do need an npm package, call it from `.art` too (`use "pkg" { x }`). Imperative code goes in a `.ts` file instead: code that drives the DOM or a canvas, or runs heavy loops (an animation or physics loop, canvas or WebGL drawing, a parser), and the wrapper of a library that owns its DOM (a map, a chart). Not in `.ts`: mock data, constants, date or money formatters, small wrappers around npm functions. What you import from `.ts` arrives as `Any`: the checker can't verify it, and `art check` warns (`MODULE_COULD_BE_ART`) when a module could be ArtScript.
<!-- artscript:end -->

The loop that keeps it cheap

1
Read the spec onceAbout 3.4K tokens describe the whole language (the core spec, 1.9K, is enough for a small app). With prompt caching it is billed at the cache rate after the first request.
2
Write .art filesOne file can hold the models, the api, the pages and the tests. Expressions are plain JavaScript, so nothing new to learn there.
3
Check, fix, repeatart check --ai returns one JSON line per error with the fix. Most retries are a single small patch.
4
Verify behaviortest blocks click, type and read the screen in a simulated browser: art test runs them with a fresh database.
5
Change with patchesFor later changes the agent reads art context for the part it needs and sends an art patch instead of rewriting files.

A prompt that works

text
You are building a web app in ArtScript. The spec is attached (ARTSCRIPT.md).
Write the app in src/app.art. After every change run `npx art check --ai`
and fix what it reports. Add test blocks for the main flows and run `npx art test`.
For changes to existing code, read `npx art context <Component>` and send an art patch.
Why it costs lessFewer output tokens per feature (no imports, hooks or boilerplate), a backend that is one line per resource, errors that carry their fix, and edits that send only what changes. The benchmarks page has the measured numbers per model.See the benchmarks →