Quick start
A0 uses typed functions, one operation per line and unsigned integer arithmetic. Function views let a model submit patches without rewriting the file.
1. Install
brew install a0
curl -fsSL https://raw.githubusercontent.com/Joe-Simo/a0/main/install.sh | sh2. Write and run
# hello.a0: compute p0 * p1 + p2
fn affine u32 u32 u32 -> u32
a mul p0 p1
b add a p2
ret b
end
# a0 run hello.a0 affine 6 7 1
433. Edit it
Ask for a view with a0 view hello.a0 affine; it prints the function under a handle (e0) with its revision. Reply with the handle, then edits, one per line:
id op args replace instruction id, or insert it before ret
id op args @ x insert after instruction x
-id delete instruction id
ret x change the result
fn ... end add or replace a whole function (program handle g0)
-fn name remove a functionThe edit is applied only if it parses, type-checks and was written against the current revision. Rejected edits leave the source unchanged and return a diagnostic. Some diagnostics include a suggested fix.
4. Connect an agent
a0 mcp . serves A0 to an agent over stdio with seven tools: a0_open, a0_program, a0_apply, a0_check, a0_run, a0_emit and a0_save. In Claude Code:
claude mcp add a0 -- a0 mcp .
npx skills add Joe-Simo/a0The second line installs the Agent Skill, which loads the primer and the edit protocol on demand. Configurations for other agents are in the repository.
Configurations for other agentsThe primer
A compact language reference for model prompts. The sections below explain each construct.
A0: `fn NAME T... -> T`, lines `ID OP ARG...`, `ret ARG`, `end`. Types u32 bool, arrays u32x4, records (u32,bool). Params p0 p1... Args: earlier ID, pN, u32 literal, true, false. Ops exact mod 2^32.
add sub mul and or xor (bool too) shl shr (count&31) div (b=0: 4294967295) rem (b=0: a) eq ne lt le gt ge (unsigned, -> bool) select c x y
call F a... | fold F n s a... state=s; i<n: state=F(state,i,a...)
arr e... | rec e... | get a i (i mod N) | set a i v | at r k | put r k v
EDIT: reply bare edit lines, e.g. `c add a b` (replaces c or inserts before ret; `c add a b @ x` inserts after x), `-c`, `ret c`, `fn f ...` (adds/replaces a function), `-fn f`.
Programs and functions
A program is a list of functions. A function is a header fn NAME T... -> T, then one instruction per line ID OP ARGS, then ret ARG (or ret OP ARGS, which names a fresh node), then end. Names are lowercase identifiers. Parameters are p0, p1, ... in header order. An argument is an earlier ID in the same function, a parameter, a u32 literal, true, or false. There are no forward references, no recursion, and no nested expressions.
# clamp p0 into [p1, p2]
fn clamp u32 u32 u32 -> u32
lo lt p0 p1
hi lt p2 p0
a select lo p1 p0
r select hi p2 a
ret r
endTypes and values
u32 is a 32-bit unsigned integer. Arithmetic wraps modulo 2^32 in the default profile. bool is true or false. Arrays u32xN and records (T,T,...) are values: set and put return updated values without changing the original. io is a linear token; each io value must be used exactly once so the checker can track output order.
Iteration
Use fold and loop to repeat calls to an earlier function: the step function receives the state, the index, and any extra arguments, and returns the next state. loop adds a predicate function that is checked before each iteration. A literal count is checked against a per-function budget when the program is checked. A variable count is bounded by fuel (a step budget) in the reference interpreter, used as the oracle in target verification; compiled targets have no execution budget.
# sum of squares 0..n-1 with fold; the step is an earlier function
fn sqstep u32 u32 -> u32
s mul p1 p1
r add p0 s
ret r
end
fn sumsq -> u32
r fold sqstep 10 0
ret r
endModules
A file starts with zero or more use "path.a0" lines, relative to the file. The linker loads every used file once, orders them by dependency, and checks the result as one program with one namespace. Cycles and duplicate function names are rejected, and diagnostics name the file and line.
use "ui.a0"
use "../examples/life.a0"
fn page io -> io
a call open p0 5
b call close a
ret b
endViews and edits
A function view includes an edit handle (e0) and callee signatures. A program view has a program handle (g0) and can be scoped to a target, its transitive callees and its direct callers. Its size depends on those dependencies. The revision is a short hash of the program text; an edit written against an older revision is rejected rather than applied to code that has moved. A reply is the handle line followed by edits, one per line, as in the quick start.
# a view of clamp, then a reply that fixes the upper bound
e0 fn clamp u32 u32 u32 -> u32
lo lt p0 p1
hi lt p2 p0
a select lo p1 p0
r select hi p2 a
ret r
# reply
e0
hi lt p2 a
r select hi p2 aDiagnostics
Diagnostics identify parse, type, structure, handle, revision and resource-limit errors. They report the location and cause where available; some include a suggested fix. Ambiguous edits are rejected.
Operations
| Operation | Meaning |
|---|---|
| mov x | the value x |
| add sub mul a b | wrapping arithmetic modulo 2^32 |
| and or xor a b | bitwise on two u32; logical on two bool |
| shl shr a n | shift by n & 31; shr is logical |
| div a b | unsigned quotient; b = 0 gives 4294967295 |
| rem a b | unsigned remainder; b = 0 gives a |
| eq ne a b | equality on two u32 or two bool, result bool |
| lt le gt ge a b | unsigned comparison, result bool |
| select c x y | x if c else y; both are computed, so no effects inside |
| call F a... | call an earlier function |
| fold F n s a... | state = s; for i in 0..n-1: state = F(state, i, a...) |
| loop P F n s a... | fold that stops before iteration i when P(state, i, a...) is false |
| arr e... / rec e... | build an array or a record |
| text "..." | an array of UTF-8 bytes |
| get a i / set a i v | read or copy-with-update at index i mod N |
| at r k / put r k v | read or copy-with-update of field k (a literal) |
| read t / write t v / puts t a | io: read one word (0 when exhausted) as (u32,io); write one word; write length then elements |
Bounds and safety
Static caps: 65536 functions per program (also after linking), 4096 instructions per function, 64 parameters, arrays up to 65536 elements (1024 on the hardware and GPU targets), literal iteration budget 2^24 per function. io output is bounded by the caller's buffer. There is no heap, recursion or exception handling. In the default profile, div and rem by zero have defined results, shifts mask the count, and indices wrap modulo the array length.
Targets and CLI
a0 check <file.a0> # parse, type, validate; diagnostics with codes
a0 run <file.a0> <fn> <args...> # reference interpreter
a0 emit <target> <file.a0> [out] # arm64 x86_64 riscv64 arm32 avr wasm c js java sv
a0 emit c --parallel[=auto|gpu] <file.a0> # automatic parallel folds: threads, or Metal
a0 wasm <file.a0> <out.wasm> # wasm32 through the C backend, Clang, and wasm-ld
a0 view <file.a0> <fn> # dependency-scoped view with an edit handle
a0 patch <file.a0> <patch> # apply a revision-checked patchTargets: AArch64, x86-64, 64-bit RISC-V, 32-bit ARM and AVR from A0's own code generators; wasm32 directly (emit wasm) or through C (a0 wasm); C; JavaScript; the JVM (Java source); .NET (C# source); Metal for the GPU; and clocked SystemVerilog for FPGA and ASIC. Native output exports C-ABI symbols named a0_NAME. JavaScript output is an ES module; Java output is an ordinary class. C# and Metal come from the verification tools (bun run dotnet, bun run gpu). The benchmarks page lists which targets and cases are checked against the reference interpreter.
--parallel makes the C backend split reductions (add, mul, and, or, xor, min, max) and element-wise array maps across threads when a cost model says the loop is large enough; --parallel=gpu also offloads to Metal when built as Objective-C. Results are the same bits as the serial program.