ilo

Token-minimal language for AI coding agents.

AI agents pay three costs per program: generation tokens, error feedback, retries. ilo cuts all three: 0.33× the tokens and 0.22× the characters of Python, type-verified before execution.

Why ilo makes agents more efficient

	Python	ilo	saving
Token count	~30	~10	67%
Characters	~90	~20	78%

• Shorter programs: 0.33× tokens, 0.22× characters vs Python
• Verified first: type errors caught before execution; agent gets ILO-T004 not a stack trace
• Compact error codes: one token, not a paragraph; agents correct faster, fewer retries
• Prefix notation: eliminates parentheses; token-optimal form for AI generation

Install

Claude Code (CLI, recommended)

/plugin marketplace add ilo-lang/ilo   # add the marketplace (once)
/plugin install ilo-lang/ilo           # install the plugin + teach the agent ilo

Cowork (web)

Browse Plugins → Add marketplace from GitHub → ilo-lang/ilo → install. Binary auto-installs via npm.

npm / npx (any platform with Node 20+)

npx ilo-lang 'dbl x:n>n;*x 2' 5   # run on-demand (no install needed)
npm i -g ilo-lang                   # or install globally

Note: npm/WASM runs interpreter mode only. HTTP builtins (get, $, post) are not available; use the native binary for network access.

macOS / Linux (one-liner)

curl -fsSL https://raw.githubusercontent.com/ilo-lang/ilo/main/install.sh | sh

Direct download

# macOS Apple Silicon
curl -fsSL https://github.com/ilo-lang/ilo/releases/latest/download/ilo-aarch64-apple-darwin -o /usr/local/bin/ilo && chmod +x /usr/local/bin/ilo

# macOS Intel
curl -fsSL https://github.com/ilo-lang/ilo/releases/latest/download/ilo-x86_64-apple-darwin -o /usr/local/bin/ilo && chmod +x /usr/local/bin/ilo

# Linux x86_64
curl -fsSL https://github.com/ilo-lang/ilo/releases/latest/download/ilo-x86_64-unknown-linux-gnu -o /usr/local/bin/ilo && chmod +x /usr/local/bin/ilo

# Windows (PowerShell)
Invoke-WebRequest -Uri https://github.com/ilo-lang/ilo/releases/latest/download/ilo-x86_64-pc-windows-msvc.exe -OutFile ilo.exe

From source

cargo install ilo
# or from git:
cargo install --git https://github.com/ilo-lang/ilo

What it looks like

Python:

def total(price: float, quantity: int, rate: float) -> float:
    sub = price * quantity
    tax = sub * rate
    return sub + tax

ilo:

tot p:n q:n r:n>n;s=*p q;t=*s r;+s t

0.33× the tokens, 0.22× the characters. Same semantics.

Real-world data pipeline: fetch JSON, parse, filter, sum:

fetch url:t>R ? t;r=($!url);rdb! r "json"
proc rows:L ?>n;clean=flt pos rows;sum clean
pos x:?>b;>x 0

Three functions, no boilerplate. $! auto-unwraps HTTP. rdb! auto-unwraps parse. >> chains transforms.

Teaching agents

Agent Skills (zero friction)

ilo ships as an Agent Skill. Install the plugin and the agent learns ilo automatically; no manual context loading needed.

Surface	How to use ilo
Claude Code (CLI)	Add marketplace then install (see Install)
Claude Cowork (web)	Browse Plugins → install ilo (binary auto-installs via npm)
Claude API / Console	Run ilo help ai locally, paste output into system prompt

Other agents (Codex, Cursor, Copilot, etc.): copy skills/ilo/ into your agent's skills directory. Any tool supporting the Agent Skills standard will pick it up.

Note: Sandboxed agents (Codex etc.) may lack filesystem/network access. Pre-install ilo in the container and use context loading instead.

Context loading

ilo help ai          # ~16-line ultra-compact spec for LLM consumption
ilo help lang        # full spec

Fine-tuning

Train on ilo programs and error feedback loops. Best for production agents writing a lot of ilo. Not yet available as a hosted service.

Running ilo

ilo 'tot p:n q:n r:n>n;s=*p q;t=*s r;+s t' 10 20 30   # → 6200
ilo program.ilo 10 20 30                                 # from file

First arg is code or a file path (auto-detected). Remaining args are passed to the first function. Name a function to select it in multi-function programs:

ilo 'dbl x:n>n;s=*x 2;+s 0 tot p:n q:n r:n>n;s=*p q;t=*s r;+s t' tot 10 20 30

Higher-order functions: map, flt, fld take a function name as first arg:

ilo 'sq x:n>n;*x x main xs:L n>L n;map sq xs' main 1,2,3,4,5   # → [1, 4, 9, 16, 25]
ilo 'pos x:n>b;>x 0 main xs:L n>L n;flt pos xs' main -3,-1,0,2,4  # → [2, 4]
ilo 'add a:n b:n>n;+a b main xs:L n>n;fld add xs 0' main 1,2,3,4,5  # → 15

Pipe >>: pass result of left as last arg to right:

ilo 'sq x:n>n;*x x pos x:n>b;>x 0 main xs:L n>L n;xs >> flt pos >> map sq' main -3,-1,0,2,4
# → [4, 16]

Pass list arguments with commas:

ilo 'f xs:L n>n;len xs' 1,2,3         # → 3
ilo 'f xs:L t>t;xs.0' 'a,b,c'         # → a

Interactive REPL:

ilo repl                     # start interactive session

Define functions, evaluate expressions, accumulate state. nvim-style commands: :q :w file.ilo :defs :clear :help.

Help & language spec:

ilo help                     # usage and examples
ilo help lang                # full language specification
ilo help ai                  # compact spec for LLM consumption (~16 lines)

Static verification: all programs verified before execution. Reports all errors at once with stable codes:

ilo 'f x:n>n;*y 2' 5
# error[ILO-T004]: undefined variable 'y'
#   = note: in function 'f'

ilo 'f x:t>n;*x 2' hello
# error[ILO-T009]: '*' expects n and n, got t and n
#   = note: in function 'f'

ilo --explain ILO-T004              # explain an error code
ilo 'f x:n>n;*x 2' --explain       # explain what the code does

Language features

Prefix and infix notation:

+*a b c            # (a * b) + c      saves 4 chars, 1 token
>=*+a b c 100      # ((a + b) * c) >= 100   saves 7 chars, 3 tokens

Infix also works: a + b, x * y + 1. Across 25 expression patterns: 22% fewer tokens, 42% fewer characters with prefix vs infix. See the prefix-vs-infix benchmark.

Auto-unwrap ! eliminates Result matching boilerplate:

# Without !: 12 tokens
ilo 'inner x:n>R n t;~x outer x:n>R n t;r=inner x;?r{~v:~v;^e:^e}' 42

# With !: 1 token
ilo 'inner x:n>R n t;~x outer x:n>R n t;~(inner! x)' 42
# → 42

HTTP GET: get url or $url (terse alias), returns R t t:

ilo 'f url:t>R t t;$url' "http://httpbin.org/get"       # → ~{ ... }
ilo 'f url:t>R t t;~($!url)' "http://httpbin.org/get"   # auto-unwrap

Environment variables: env key returns R t t:

ilo 'f k:t>R t t;env k' "HOME"    # → ~"/Users/dan"
ilo 'f k:t>R t t;env! k' "HOME"   # auto-unwrap

File I/O: format auto-detected from extension:

ilo 'f p:t>R ? t;rd p' data.csv    # → Ok([[row1col1 …] …])
ilo 'f p:t>R ? t;rd p' data.json   # → Ok(parsed JSON)
ilo 'f p:t>R ? t;rd p' notes.txt   # → Ok("raw text")
ilo 'f p:t>R ? t;rd p "json"' data.csv   # force format
ilo 'f s:t>R ? t;rdb s "csv"' "a,b\n1,2" # parse buffer

Data scripting:

ilo 'f s:t>t;trm s' "  hello  "        # → "hello"
ilo 'f xs:L t>L t;unq xs' a,b,a,c,b   # → ["a" "b" "c"]
ilo 'f>t;fmt "{} + {} = {}" 1 2 3'     # → "1 + 2 = 3"

Aggregation & reshape:

ilo 'f xs:L n>n;sum xs' 1,2,3,4,5      # → 15
ilo 'f xs:L n>n;avg xs' 2,4,6          # → 4
ilo 'f s:t>L t;rgx "\d+" s' "abc 123"  # → ["123"]

Imports:

# math.ilo: dbl n:n>n;*n 2
# main.ilo: use "math.ilo"  run n:n>n;dbl n
ilo main.ilo run 5           # → 10

Environment files: .env and .env.local loaded automatically. .env.local takes priority; existing env vars are not overwritten:

echo 'ANTHROPIC_API_KEY=sk-...' > .env
ilo 'f k:t>R t t;env! k' ANTHROPIC_API_KEY

Output formats:

ilo 'code' -a               # ANSI colour (default for TTY)
ilo 'code' -t               # plain text
ilo 'code' -j               # JSON (default for piped output)

Formatter:

ilo 'code' --dense / -d     # dense wire format (agents)
ilo 'code' --expanded / -e  # expanded human format

Other modes:

ilo 'code' --emit python     # transpile to Python
ilo program.ilo --bench tot 10 20 30  # benchmark

Run tests:

cargo test

For integrators

Tool declarations: external calls wired to HTTP endpoints via a JSON config:

ilo program.ilo --tools tools.json args...

tools.json:

{
  "tools": {
    "get-user": {
      "url": "https://api.example.com/get-user",
      "method": "POST",
      "timeout_secs": 5,
      "retries": 2
    }
  }
}

ilo serialises call args as {"args": [...]} and deserialises the JSON response back to ilo values.

MCP servers: connect any MCP server to give ilo access to its tools:

ilo program.ilo --mcp mcp.json args...

mcp.json uses Claude Desktop format. MCP tools are injected as tool declarations before verification, so types are checked end-to-end.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

See examples/mcp.json for a working example.

Backends:

ilo 'code' args              # default: Cranelift JIT → interpreter fallback
ilo 'code' --run-interp ...  # tree-walking interpreter
ilo 'code' --run-vm ...      # register VM (bytecode compiled)
ilo 'code' --run-cranelift . # Cranelift JIT
ilo 'code' --run-jit ...     # custom ARM64 JIT (macOS Apple Silicon only)

Documentation

Document	Purpose
SPEC.md	Language specification
examples/	Runnable example programs (also cargo test regression suite)
MANIFESTO.md	Design rationale
research/JOURNEY.md	Design journey: syntax variants, benchmarks, research index
skills/ilo/	Agent Skill (for AI coding agents)
research/TODO.md	Planned work
research/OPEN.md	Open design questions

Principles

1. Token-conservative: every choice evaluated against total token cost: generation, retries, error feedback, context loading.
2. Constrained: small vocabulary, closed world, one way to do things. Fewer valid next-tokens = fewer wrong choices = fewer retries.
3. Self-contained: each unit carries its own context: deps, types, rules.
4. Language-agnostic: structural tokens (@, >, ?, ^, ~, !, $) over English words.
5. Graph-native: programs express relationships navigable as a graph, not just linear text.

Guards instead of if/else: flat statements that return early and chain vertically. No nesting depth, no closing braces. Match instead of switch: no fall-through.

See MANIFESTO.md for full rationale.

Design journey

We explored 9 syntax variants before settling on the current design. See research/JOURNEY.md for the full comparison table, key findings, and all research documents.

Community

• r/ilolang — discussion, feedback, and updates

  _  _          _
 (_)| | ___    | |  __ _  _ __    __ _
 | || |/ _ \   | | / _` || '_ \  / _` |
 | || | (_) |  | || (_| || | | || (_| |
 |_||_|\___/   |_| \__,_||_| |_| \__, |
                                   |___/