CX+AI with an AI assistant

This page is for using an AI assistant to write CX+AI. It covers the one thing you must do before you ask it anything, which tool to use for the way you like to work, and the prompts themselves — copy them whole.

Everything in section 5 was run. Nothing is claimed here that the table there does not show.

---

1. What your assistant does not know

No model has been trained on CX+AI. It is a young language with five public releases behind it, so every assistant you open — however good — knows nothing about it. That is not a criticism of the model. It is a fact about the training data, and it has one specific consequence you should expect:

Asked for CX+AI, an assistant writes C in CX+AI costume. It reaches for malloc, for a fixed array, for sprintf at every boundary, and it hard-codes the decisions that CX+AI exists to keep changeable. The syntax comes out close enough to compile. The program teaches nothing and throws away most of what you installed.

The fix takes two minutes and it is the whole point of this page.

Give it the rules first

Your install has a docs/ folder. Twenty-three manuals are in it, and one of them is written for exactly this moment:

CX_For_AI.html is a conversion pass in priority order — the same checklist this project holds its own AI contributors to, published unchanged. It names the C reflex, says what CX+AI does instead, and says why. It is about 17 KB, which fits in any assistant's context with room to spare.

Hand over CX_For_AI.html first, always. What section 5 measures is that it changes what the assistant reaches for — not that it makes the program compile. Both models stopped writing C with it attached and started writing CX+AI with guessed builtin names, which is a better problem and a different one. The Builtins Reference is what fixes the second half, so ask for both.

---

2. Which tool

Three shapes, and the honest case for each. Product names are as of September 2026 and they rot faster than this page will be updated; the shapes do not.

A terminal agent that can read your folder

Claude Code, OpenAI's Codex CLI, Gemini CLI, and the like.

This is the best fit for the loop, though nothing on this page measures one tool against another (section 5 tested models and documents, not editors). The argument is structural rather than empirical: point it at your install folder and it reads docs/ itself — you do not paste anything. It writes the .cx file, runs cx file.cx --run, reads the compiler's error, and fixes it, without you being the courier between the two. CX+AI's errors are numbered and written to be read — a code, then a sentence saying what the rule is — which is worth more to an agent that can see them than to one being told about them second-hand.

The prompts in section 3 are written for this shape first. They work in the others.

An editor with an assistant

VS Code with Copilot or the Claude or Codex extensions, Cursor, Zed.

Be aware of what you are not getting: CX+AI ships no editor extension. There is no syntax highlighting for .cx, no language server, no completions and no inline error squiggles. Set your editor's file association for .cx to C — the languages are close enough that C highlighting reads correctly for most of a file — and let the assistant do the CX+AI-specific work.

The assistant still has to be given the docs. Most editor assistants let you attach a file to the conversation or point at one in the workspace; put the install's docs/ folder inside your project and reference it from there.

A chat window

claude.ai, ChatGPT, Gemini in a browser.

Works. Paste or attach CX_For_AI.html at the start. If your product has Projects or custom instructions, put it there once and it carries across sessions, which removes the only real annoyance.

It is the slowest loop, and the reason is structural: you copy the code out, run it yourself, and paste the error back. Every round trip is manual. For a first look that is fine. For a real program, use one of the shapes above.

---

3. The prompts

Copy these whole. They are deliberately complete, and deliberately negative in places — most of what an assistant gets wrong here is an assumption it brought with it, not a fact it was missing.

The opener

Send this first, with CX_For_AI.html attached. It is the standing instruction for the conversation.

You are writing CX+AI, a compiled programming language. No model has been
trained on it, so do not answer from memory: if you are not certain a name
exists, say so rather than guessing.

Read the attached docs/CX_For_AI.html and apply its rules in priority order
before you write a line. It is a conversion pass, not a style guide.

Hold every program to these:
- It must compile with `cx <file>.cx --run` AND with
  `cx <file>.cx --run -P pcode=risc`. A program that only builds one way is
  not finished.
- Declarations go at the top of a function. Function return types are a suffix
  on the NAME: `function total.i(...)`, `.s` string, `.f` float, `.v` void.
  Omitting the suffix silently means int.
- When you are unsure of a builtin's name, look it up in
  docs/CX_Builtins_Reference.html rather than guessing. A wrong name is a
  compile error that names itself; a guessed one wastes a round trip.
- Answer with ONE fenced code block tagged cx, and at most two sentences
  after it.

A first program

Write a CX+AI program that prints one line per ship -- the name, the crew, and
the hull as a percentage -- from this document. The document is known when you
write the program, so put it in the source rather than reading a file.

{ "fleet": "Outer Reach",
  "ships": [ { "name": "Nostromo", "crew": 7,  "hull": 0.82 },
             { "name": "Sulaco",   "crew": 12, "hull": 1.0  },
             { "name": "Patna",    "crew": 3,  "hull": 0.41 } ] }

The thing to watch for in the answer is whether the document is written as itself in a _json block, or assembled key by key with builder calls. Both run. Only the first is what CX+AI is for, and it is the first rule on the page you attached.

A program with a rule

Write a CX+AI program in which the shipping charge is a RULE the running
program could be handed a new version of -- not an `if` compiled into the code.
Orders of 50 or more ship free; everything else pays 4.95. Print the rule's own
text, then apply it to three orders of 20, 50 and 120 and print what each
one pays.

Say rule and say while it runs. Ask for "a function that calculates shipping" and you will get a function that calculates shipping, correctly, and you will have learned nothing about the language.

A program that asks a model

Write a CX+AI program that asks a language model one question and prints the
answer. Configure it with ONE options document that tries a local model first
and a cloud provider second, so the program still answers when the network is
down. Print the error text if the call fails rather than printing an empty
answer.

The trap to check for: an assistant that reaches for HTTP calls and JSON assembly by hand, because that is how every other language does this. In CX+AI the AI surface is builtins and one options document.

Converting a small C program

This is the prompt that most directly exercises the conversion pass, so it is the best single test of whether your assistant actually read the rules.

Convert this C program to idiomatic CX+AI. Keep what it does; change how it
says it.

<paste the C here>

Fixing a compile error

Paste the source and the compiler's whole error. Do not summarise it — the message is long on purpose and the second half is usually the fix.

This CX+AI program does not compile. Here is the source and the compiler's own
error. Give me the fixed program, and one sentence saying what the rule is.

SOURCE
<paste>

ERROR
<paste the whole error line, including the code>

When the assistant writes C in CX+AI costume

It will happen, including with the rules attached. This is the correction:

That program compiles, but it is C wearing CX+AI syntax. Go back to
docs/CX_For_AI.html and apply it properly:

- What in this program might change while it runs? That belongs in a document
  or a rule, not in an `if`.
- You allocated by hand or used a fixed array. Reach for json, then map, then
  list before an array.
- You converted at a boundary (atoi, sprintf, strcpy). CX+AI coerces; assign
  it.
- Every function you declared needs a return suffix on its name.

Rewrite it, and say in one line per change what you moved and why.

---

4. The loop

There are two commands, and that is all the tooling there is.

cx myprogram.cx --run

Read the error, fix, repeat. Then, before you call it done:

cx myprogram.cx --run -P pcode=risc

A program that only runs one way is not finished, and this is not a formality. In the run behind section 5, every program that failed to build natively also failed on the register VM, and every one that built natively built on both — 22 programs measured on both backends, no disagreement. So the second run is cheap insurance rather than a second chance, and when the two ever do disagree you have found something worth reporting. The same source compiles to a native binary and runs on the register VM, and the two are meant to agree. A program that runs natively and fails on the VM has usually reached for something that only exists on one side, which is worth knowing before you build on it.

And handing the error back does work, but not on its own. Measured in section 5: one round trip fixed 2 of 9 failing programs. Take the round trip — it costs nothing — and when the second attempt comes back with the same error, stop repeating and give the assistant docs/CX_Builtins_Reference.html instead. That is what the remaining failures were made of.

---

5. What was tested

Every prompt in section 3 was run through two real assistants, twice each — once with nothing, once with CX_For_AI in front of it — and every answer was compiled on both backends. The numbers below are that run. Nothing elsewhere on this page is claimed beyond them, and where something is reasoning rather than measurement it says so.

The setup. Two models with no CX+AI in their training data, reached through a CX+AI program using the AI surface this page's section 3 teaches: openai/gpt-oss-120b and qwen/qwen3.8-27b, September 2026. Six prompts. One sample per cell — these models are not deterministic, so read a single row as an anecdote and the column totals as the result. Answers were compiled, not run: the question was whether the program builds on both backends, and running code a model wrote on somebody's machine is a different decision.

One difference from what this page tells you to do. The reference was sent as its markdown source rather than as CX_For_AI.html. It is the same document — the HTML page is generated from that markdown — but the markup is about two and a half times the bytes for no extra content, and the account used here has a request-size ceiling. When you attach the HTML to a chat, the tool extracts the text anyway. When a terminal agent reads the file, it sees the markup. Neither changes what the model is told.

What was NOT tested, said first. No comparison of tools — Claude Code against Cursor against a chat window. Section 2 is reasoning about the shape of the loop, not a measurement, because what varies between those tools is who does the copying, not what the model receives. What is measured here is the thing you actually control: what you hand the assistant.

The result, and it is not the simple one

Read that twice, because both columns moved and they moved in opposite directions, the same way for both models:

• The reference changes what the model writes. Rules score up in both cases. Concretely: C reflexes (malloc, sizeof, strcpy, sprintf, atoi) appeared in 2 of 11 programs written without it and in 0 of 12 written with it. A literal _json or _rules block — the first rule on the page — appeared 0 of 11 times without it and 7 of 12 times with it.
• The reference does not make the program compile. First-attempt build rate went down for both models.

Those two facts are the same fact. Without the reference a model writes C, and C-shaped code that happens to be accepted by a C-derived language sometimes builds. With the reference it reaches for _json, for rules, for maps and containers — the right shape — and then has to spell all of that correctly from a language it has never seen. The failures move from wrong language to right language, guessed names.

You can see it in one pair. The conversion prompt, same model, same day:

Without the reference — it is the C program with function written on it, and it says so itself:

    ship_t* fleet;
    fleet = malloc(3 * sizeof(ship_t));   // assuming malloc is available
    strcpy(fleet[0].name, "Nostromo");    // assuming strcpy exists
    printf("%-10s %2d\n", ...);           // assuming printf exists

With the reference — the document is a document, the loop reads it, and the remaining mistake is a guessed builtin name (also confessed):

    _json fleet {
      [ { "name": "Nostromo", "crew": 7 }, ... ]
    }
    // `jsonLen` and `jsonGet` are the usual CX JSON helpers
    for (i = 0; i < jsonLen(fleet); i++) { ... }

The second is wrong and the first is hopeless. jsonLen and jsonGet do not exist; a subscript and ->count do. That is a lookup, and it is why the opener tells the assistant to check docs/CX_Builtins_Reference.html rather than guess.

What the failures actually were

Every failing program, both rounds, by the compiler's own code:

Five of twenty-one are a builtin's name or arity — exactly what the Builtins Reference answers, which is why this page tells you to hand that one over too. That recommendation is reasoned from this table, not measured: the arm that would have tested it could not be sent. The reference plus the full Cheatsheet exceeded the request-size limit of the account used (HTTP 413), so "does more documentation help further" is unmeasured here, and this page does not claim a number for it.

The two gcc messages are a defect in CX+AI, not in the models, and they are recorded rather than hidden: in those two cases the compiler accepted the source and let the C compiler complain about a generated file the author never wrote. That is the one thing on this page that should not happen, it has been filed, and you may see it. If a build fails with a message naming a .c file in a temp directory, that is this, and the mistake is still in your .cx file.

Does handing the error back work?

Section 4's whole loop is: read the error, paste it back, repeat. Measured, once, on every program that failed with the reference attached:

2 of 9 fixed by a single round trip.

So the loop is real and it is not magic. One round trip is worth taking — it costs nothing — and it will not usually finish the job on its own. Two of the remaining seven came back with a different error, which is progress; the rest repeated themselves, which is the signal to give the assistant the Builtins Reference rather than another turn.

What the rules score cannot see

The score counts eight things a grep can decide — no hand allocation, no redim, no retired call forms, no _C{}, no convert-at-the-boundary, return suffixes present, a container reached for before an array, a literal document where one was asked for. It measures whether the C reflex was avoided. It cannot tell you the program is good.

One answer scored 7 of 8 and compiled cleanly by printing three string literals instead of converting the program it was given. Every check passed. It had thrown the task away. Read the code.

The two lines worth taking away

Which prompt produced the best CX+AI: the first one — a known document and a loop over it — with the reference attached. Both models scored 8 of 8 on it and one compiled first time. It is the prompt where the language's first rule and the task are the same thing.

Which assistant wrote C in costume with the rules in front of it: neither. That is the clean part of the result. Without the reference, openai/gpt-oss-120b produced the purest costume on this page — malloc, sizeof, strcpy, and three comments admitting it was guessing. With the reference attached, no program from either model contained a single C reflex. What it could not give them was the names, and no rules document can: that is the Builtins Reference's job, and asking for it is one line in your opener.