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.Cursor, Windsurf and other MCP clients take the same command in their config:
llms.txtThe entry point for AI crawlers and agents: what ArtScript is and where each document is.
Full spec · ~2900 tokensThe whole language: declarations, state, the backend, the view, tests and the rules the compiler checks. Give it before the first line of code.
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.
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:claude mcp add artscript -- npx art mcp{
"mcpServers": {
"artscript": { "command": "npx", "args": ["art", "mcp"] }
}
}| Tool | What it does |
|---|---|
| art_spec | The language spec (full, or the short edit version). |
| art_check | Typechecks the project; errors as JSON with expected, actual and fixes. |
| art_context | The project map, or a component's source with every patch path. |
| art_patch | Applies a structured edit: atomic and typechecked, nothing is written on error. |
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.# Instructions for AI agents
This project uses **ArtScript** (`.art` files in `src/`). The full language spec is in `ARTSCRIPT.md`: read it before writing code. 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>`.
- 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.
The loop that keeps it cheap
Read the spec onceAbout 3K tokens describe the whole language. With prompt caching it is billed at the cache rate after the first request.
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.
Check, fix, repeatart check --ai returns one JSON line per error with the fix. Most retries are a single small patch.
Verify behaviortest blocks click, type and read the screen in a simulated browser: art test runs them with a fresh database.
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
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 →