---
title: Introduction
description: Tellscript is an open Markdown format that records what your software must do, how it looks and why, so any AI agent can build it and every new model can rebuild it better.
url: https://tellscript.com/docs
last_updated: 2026-09-27
---

# Introduction

Tellscript is an open format for the part of your software that should outlive its code. A Tellscript is a folder of Markdown files next to your code. It records what the product must do, how it must look, what other systems rely on and why things are the way they are. Every rule has a stable id and a check that fails when the rule breaks.

Any coding agent can read it. Claude Code, Codex, Cursor, Gemini CLI or an open model builds the code from it, and when a better model arrives, it builds the next **edition** of the same app: the fixed rules stay, the free parts get better.

## Why a new format

AI writes code, images and documents in minutes. How and why they came out that way is forgotten the moment they exist. The next agent tidies up and brings back the bug that was the reason for an odd rule. The tenth image no longer matches the first. Every rebuild copies the last one, flaws included.

Tellscript keeps the mould instead of the cast. The code becomes an output you can throw away; the Tellscript is the source.

## How it works

1. **Write it down.** One file per feature: intent, numbered statements, the look as a reference image, the reasons as decisions.
2. **Bind it.** Every statement points to the test, reference image or recipe that proves it.
3. **Build and rebuild.** Any agent builds an edition from the Tellscript. The checks decide whether it is accepted.

```tell file=tell/features/cart.tell.md
## Behaviour · fixed
C1 When the goods reach €50.00,
   shipping is free.
   → cart.spec#free-shipping
C2 When a second voucher arrives,
   it is declined with a notice.
   → cart.spec#one-voucher
```

## What is in these docs

| Section | Read it when |
|---|---|
| [Quickstart](/docs/quickstart) | you want a first Tellscript in an afternoon |
| [Teach your agent](/docs/agents) | you want Claude Code, Codex, Cursor or another agent to know the format |
| [The format](/docs/files) | you write or review Tellscripts and want the exact rules |
| [Checks](/docs/checks) and [editions](/docs/editions) | you rebuild with a new model or guard an app against drift |
| [Example](/docs/example) | you learn best from a complete, working set of files |

> [!NOTE]
> Tellscript is plain Markdown in your repository. There is no service to sign up for and nothing to install to start. Tools that make it more comfortable are in development; see [the CLI preview](/docs/cli).