{
"markdown": "# ilo\n\n*A programming language AI agents write, not humans. Named from [Toki Pona](https://sona.pona.la/wiki/ilo) for \"tool\".*\n\n> Experimental pre 1.0 language, expect breaking changes. See [STABILITY.md](./STABILITY.md) for what's stable vs in-flight. Open-sourced February 2026.\n\n[](https://github.com/ilo-lang/ilo/actions/workflows/rust.yml) [](https://codecov.io/gh/ilo-lang/ilo) [](https://crates.io/crates/ilo) [](https://www.npmjs.com/package/ilo-lang) [](https://www.npmjs.com/package/pi-ilo-lang) [](https://github.com/ilo-lang/ilo#agent-specific-install) [](LICENSE)\n\n```\nPython ilo\n───── ───\ndef total(price, quantity, rate): tot p:n q:n r:n>n;s=*p q;t=*s r;+s t\n sub = price * quantity\n tax = sub * rate\n return sub + tax\n\n4 lines, 30 tokens, 90 chars 1 line, 10 tokens, 20 chars\n```\n\n**0.33× the tokens. 0.22× the characters. Same semantics. Type-verified before execution.**\n\n## Why\n\nAI agents pay three costs per program: generation tokens, error feedback, retries. ilo cuts all three:\n\n- **Shorter programs** - prefix notation eliminates parentheses; positional args eliminate boilerplate\n- **Verified first** - type errors caught before execution; agents get `ILO-T004` not a stack trace\n- **Compact errors** - one token, not a paragraph; agents correct faster, fewer retries\n\n## Install\n\n\nmacOS / Linux
\n\n```sh\ncurl -fsSL https://ilo-lang.ai/install.sh | sh\n```\n\nThe installer downloads the release binary plus its `checksums-sha256.txt` from the matching GitHub release and refuses to install if the SHA-256 doesn't match. Source: [`scripts/install/install.sh`](./scripts/install/install.sh).\n\n \n\n\nWindows (PowerShell)
\n\n```powershell\niwr -useb https://ilo-lang.ai/install.ps1 | iex\n```\n\nSame checksum verification as the Unix installer. Source: [`scripts/install/install.ps1`](./scripts/install/install.ps1).\n\n \n\n\nnpm (any platform with Node 20+)
\n\n```bash\nnpm i -g ilo-lang\n\n# or run without installing\nnpx ilo-lang 'dbl x:n>n;*x 2' 5\n```\n\n> WASM mode: interpreter only. HTTP builtins (`get`, `$`, `post`) require the native binary.\n\n \n\n\nRust
\n\n```bash\ncargo install ilo\n```\n\n \n\n\nAgent skills (Claude Code / AI agents)
\n\n```bash\nnpx skills add ilo-lang/ilo\n```\n\nUses the [skills](https://www.npmjs.com/package/skills) npm package (396K+ installs). Installs the ilo Agent Skill into Claude Code or any compatible agent.\n\n \n\n\nAgent-specific install
\n\n| Agent | Install |\n|-------|---------|\n| **Claude Code** | `/plugin marketplace add ilo-lang/ilo` then `/plugin install ilo-lang/ilo` |\n| **Claude Cowork** | Browse Plugins → Add marketplace → `ilo-lang/ilo` → install |\n| **Other agents** | Copy `skills/ilo/` into your agent's skills directory |\n\n \n\n**[All install methods →](https://ilo-lang.ai/docs/installation/)**\n\n## Quick start\n\n```bash\n# Inline\nilo 'dbl x:n>n;*x 2' 5 # → 10\n\n# From file\nilo program.ilo functionName arg1 arg2\n\n# Verb form (cargo / go / zero style; bare positional still works)\nilo run program.ilo arg1 arg2 # run\nilo check program.ilo # verify only - exit 0 if clean\nilo build program.ilo -o ./bin # AOT compile\n```\n\n**[Tutorial: Write your first program →](https://ilo-lang.ai/docs/first-program/)**\n\n## Editor support\n\nSyntax highlighting, snippets, and `--` comment handling for `.ilo` files ships in [`extensions/vscode/`](./extensions/vscode/). Install into Cursor with `cd extensions/vscode && npm run install:cursor`. VS Code marketplace publish is tracked separately.\n\n## Versioning\n\nCalVer. Releases are `YY.M` (e.g. `26.5`), patches within a month are `YY.M.P` (e.g. `26.5.1`). The version string carries recency: an agent loading `ilo spec --json ai` knows which spec applies from the version alone, no changelog lookup needed. Token-conservative (manifesto principle 1) vs semver's `0.12.1`.\n\n### Branches\n\n| Branch | Purpose | Tags |\n|--------|-----------------------------|--------------------------------------------|\n| `main` | Current release line, patches | `26.5`, `26.5.1`, `26.5.1-dev.N` |\n| `next` | Next release | `26.6-dev.N`, then clean `26.6` on cut |\n\nUniversal scheme: `-dev.N` is the only in-flight marker on either branch. Clean (no suffix) means soaked, ready, published. No RC tag.\n\n### Release flow (next release)\n\n1. Work lands on `next`\n2. Iterations tagged `26.6-dev.1`, `26.6-dev.2`, …\n3. When soaked: merge `next` → `main`, cut clean `26.6` tag on `main`\n4. `next` continues for `26.7-dev.1`\n\n### Patch flow (current release fix)\n\n1. Fix lands on `main` (direct or short-lived fix branch)\n2. Iterations tagged `26.5.1-dev.1`, `26.5.1-dev.2`, …\n3. When soaked: cut clean `26.5.1` tag on `main`\n4. Merge `main` → `next` to carry the fix forward (auto via `sync-next.yml`)\n\n### Migration from 0.x\n\nLast semver release: `0.12.1`. First CalVer release cuts on the next breaking change as `26.X`. Hard cut, no `0.13` bridge. The file version pragma ships with the CalVer cut and is optional — existing 0.x files have no pragma and verify without a diagnostic.\n\n### File version pragma\n\nOptional. ilo source files may declare the minimum required runtime with a top-of-file sigil:\n\n```\n^26.5\n-- rest of file\n```\n\n- Sigil-led (principle 4), ~3 tokens (principle 1)\n- `^` carries \"at minimum\" semantics — agents read it correctly without a spec lookup\n- First-class syntax, not a magic comment\n- Position: first line, no leading whitespace\n\nVerifier behaviour:\n\n| Case | Result |\n|---------------------------------------------------------|-------------------------------------|\n| Pragma absent | Assume latest installed runtime, no diagnostic |\n| File targets older than runtime, breaking change between| Fail with migration pointer |\n| File targets newer than runtime | Fail asking to upgrade |\n\nTooling: `ilo --version-of ` reads the pragma (returns nothing when absent); the formatter canonicalises position when present, never inserts one.\n\n## What it looks like\n\n**Guards** - flat, no nesting:\n```\ncls sp:n>t;>=sp 1000 \"gold\";>=sp 500 \"silver\";\"bronze\"\n```\n\n**Pipes** - left-to-right composition:\n```\nrun x:n>n;x>>dbl>>inc\n```\n\n**Data pipeline** - fetch, parse, filter, sum:\n```\nfetch url:t>R ? t;r=($!url);rdb! r \"json\"\nproc rows:L ?>n;clean=flt pos rows;sum clean\npos x:?>b;>x 0\n```\n\n**Sum types** - discriminated unions with exhaustive matching:\n```\ntype Shape = Circle n | Rect n n\narea s:Shape>n;Circle r=s;*r r Rect w h=s;*w h\n```\n\n**defer / errdefer** - guaranteed cleanup regardless of exit path:\n```\nopen-file path:t>R t;f=open! path;defer close f;read! f\n```\n\n**Auto-unwrap `!`** - eliminates Result matching:\n```bash\nilo 'inner x:n>R n t;~x outer x:n>R n t;~(inner! x)' 42 # → 42\n```\n\n**Batteries included** - the standard library covers what real programs need without leaving ilo:\n\n- **Math**: `sqrt`, `pow`, `exp`, `log`/`log10`/`log2`, `sin`/`cos`/`tan`, `atan2`, `clamp`, `rou`\n- **Stats**: `median`, `quantile`, `stdev`, `variance`, `cumsum`, `frq`\n- **Linear algebra**: `transpose`, `matmul`, `dot`, `solve`, `inv`, `det`, `fft`/`ifft`\n- **Lists**: `at`, `take`/`drop`, `zip`, `enumerate`, `range`, `chunks`, `window`, `flatmap`, `partition`, `setunion`/`setinter`/`setdiff`\n- **Text**: `upr`/`lwr`/`cap`, `padl`/`padr`, `chars`, `ord`/`chr`, `rgxall`, `rgxsub`\n- **Time**: `now`, `sleep`, `dtfmt`/`dtparse` (strftime, UTC)\n- **JSONL**: `rdjl` for line-by-line parsing\n- **Concurrent HTTP**: `get-many` (up to 10 parallel)\n- **Parallel**: `par-map` general fan-out with chunking; native VM opcode\n- **Tokens**: `tokcount` approximate cl100k_base token count\n\n## What shipped in 0.13\n\nHighlights from the 0.13 cycle:\n\n- **Sum types** — discriminated unions, generics, recursive, exhaustive matching ([examples/sum-types.ilo](examples/sum-types.ilo), [examples/generic-sum-types.ilo](examples/generic-sum-types.ilo))\n- **Generics** — bounded type parameters, multi-bound, VM/JIT dispatch ([examples/generics-bounded.ilo](examples/generics-bounded.ilo))\n- **Modules** — re-exports, conditional imports, lazy loading\n- **Effect sets** — declare and enforce side-effect budgets ([examples/effect-sets.ilo](examples/effect-sets.ilo))\n- **World / capability** — `world` / `world-no-net` builtins; static enforcement ([examples/capability-world.ilo](examples/capability-world.ilo))\n- **defer / errdefer** — structured cleanup ([examples/defer-basic.ilo](examples/defer-basic.ilo), [examples/errdefer.ilo](examples/errdefer.ilo))\n- **Gleam-style syntax** — `use<-` chain, `todo`/`panic`, match alternatives, multi-subject match\n- **ilo httpd** — embedded HTTP server ([examples/httpd-hello.ilo](examples/httpd-hello.ilo))\n- **run family** — `run-bg` (fire-and-forget), `run-full-env` (inherit env)\n- **Bitwise ops** — 32/64-bit; native `U32` / `U64` / `I64` types\n- **Package registry** — `ilo add` installs packages from the registry\n- **Fix plans + ilo apply** — structured agent-writable repair workflow\n- **ilo trace** — execution tracing for debugging and observability ([examples/trace-demo.ilo](examples/trace-demo.ilo))\n- **JS compile target MVP** — emit JavaScript from ilo source\n- **WASM HTTP fetch** — `$` / `get` builtins work in WASM via fetch ([examples/wasm-fetch.ilo](examples/wasm-fetch.ilo))\n- **Cranelift TCO** — tail calls via `return_call`; no stack overflow on deep recursion\n- **tokcount** — token counting builtin backed by tiktoken-rs\n- **Numeric / signal / text utility batches** — extended stdlib coverage\n\n## Teaching agents\n\nilo ships as an [Agent Skill](https://agentskills.io). Install the plugin and the agent learns ilo automatically.\n\nFor manual context loading:\n```bash\nilo -ai # compact spec for LLM system prompts\nilo help lang # full spec\n```\n\n## Key docs\n\n| | |\n|---|---|\n| **[Introduction](https://ilo-lang.ai/docs/introduction/)** | What ilo is and why |\n| **[Installation](https://ilo-lang.ai/docs/installation/)** | All install methods |\n| **[Tutorial](https://ilo-lang.ai/docs/first-program/)** | Write your first program |\n| **[Types & Functions](https://ilo-lang.ai/docs/guide/types-and-functions/)** | Core language guide |\n| **[Prefix Notation](https://ilo-lang.ai/docs/guide/prefix-notation/)** | Why prefix saves tokens |\n| **[Guards](https://ilo-lang.ai/docs/guide/guards/)** | Pattern matching without if/else |\n| **[Pipes](https://ilo-lang.ai/docs/guide/pipes/)** | Function composition |\n| **[Collections](https://ilo-lang.ai/docs/guide/collections/)** | Lists and higher-order functions |\n| **[Error Handling](https://ilo-lang.ai/docs/guide/error-handling/)** | Result types and auto-unwrap |\n| **[Data & I/O](https://ilo-lang.ai/docs/guide/data-io/)** | HTTP, files, JSON, env |\n| **[MCP Integration](https://ilo-lang.ai/docs/integrations/mcp/)** | Connect MCP servers |\n| **[CLI Reference](https://ilo-lang.ai/docs/reference/cli/)** | Flags, REPL, output modes |\n| **[Builtins](https://ilo-lang.ai/docs/reference/builtins/)** | All built-in functions |\n| **[Error Codes](https://ilo-lang.ai/docs/reference/error-codes/)** | ILO-XXXX reference |\n| **[SPEC.md](SPEC.md)** | Full language specification |\n| **[examples/](examples/)** | Runnable examples (also test suite) |\n\n## Benchmarks\n\nPer-call time (ns) across 8 micro-benchmarks. Lower is better. [Full results →](https://ilo-lang.ai/docs/reference/benchmarks/)\n\n| Language | numeric | string | record | mixed | guards | recurse | foreach | while | pipe | file | api |\n|----------|--------:|--------:|--------:|--------:|--------:|--------:|--------:|--------:|--------:|--------:|--------:|\n| Rust (native) | 496ns | 3.7us | n/a | 9.9us | 1.8us | 18.8us | 44ns | n/a | 254ns | 9.3us | 159.0us |\n| Go | 705ns | 17.2us | 107ns | 6.2us | 738ns | 21.5us | 162ns | 30ns | 31ns | 19.0us | 200.0us |\n| C# (.NET) | 6.2us | 14.6us | 554ns | 29.9us | 6.8us | 24.7us | 1.2us | 417ns | 610ns | 22.7us | 228.8us |\n| Kotlin (JVM) | 492ns | 8.2us | 265ns | 7.8us | 1.0us | 17.4us | 1.2us | 168ns | 226ns | 18.6us | 183.4us |\n| LuaJIT | 513ns | 19.0us | 149ns | 9.8us | 3.5us | 28.7us | 676ns | 48ns | 85ns | 14.7us | 63.2us |\n| Node/V8 | 569ns | 1.3us | 354ns | 5.3us | 1.0us | 46.7us | 480ns | 81ns | 191ns | 12.4us | 284.5us |\n| TypeScript | 427ns | 1.2us | 236ns | 5.4us | 1.0us | 45.9us | 421ns | 75ns | 167ns | 12.7us | 310.2us |\n| ilo AOT | 1.8us | 12.9us | 1.1us | 33.0us | 5.3us | 37.3us | 1.1us | 148ns | 126ns | n/a | n/a |\n| ilo Cranelift | 1.3us | 5.0us | 504ns | 26.2us | 3.2us | 37.2us | 935ns | 150ns | 125ns | 16.5us | 1.7ms |\n| ilo VM | 11.3us | 10.5us | 3.1us | 31.6us | 53.5us | 528.3us | 2.4us | 1.2us | 7.0us | 16.9us | 171.1us |\n| Lua | 4.0us | 39.8us | 7.5us | 49.2us | 27.0us | 339.1us | 3.8us | 967ns | 4.3us | 16.1us | 54.3us |\n| Ruby | 19.8us | 26.0us | 8.7us | 18.4us | 38.5us | 373.0us | 3.2us | 2.3us | 6.3us | 19.6us | 269.2us |\n| PHP | 6.4us | 4.0us | 4.0us | 8.2us | 25.8us | 552.9us | 1.1us | 767ns | 6.7us | 15.3us | 173.9us |\n| Python 3 | 28.1us | 12.0us | 8.5us | 28.0us | 63.3us | 717.2us | 2.1us | 2.7us | 11.0us | 20.9us | 12.2us |\n| PyPy 3 | 1.2us | 2.0us | 445ns | 20.5us | 4.3us | 107.1us | 605ns | 286ns | 470ns | 24.7us | 2.0us |\n\n*10000 iterations, Darwin arm64, 2026-03-14*\n\n## Community\n\n- **[ilo-lang.ai](https://ilo-lang.ai)** - docs, playground, and examples\n- **[hello@ilo-lang.ai](mailto:hello@ilo-lang.ai)** - get in touch\n\n## Principles\n\n1. **Token-conservative** - every choice evaluated against total token cost\n2. **Constrained** - small vocabulary, one way to do things, fewer wrong choices\n3. **Self-contained** - each function declares its deps; no globals, no ambient state\n4. **Language-agnostic** - structural tokens (`@`, `>`, `?`, `^`, `~`, `!`, `$`) over English words\n5. **Graph-reducible** - load only the relevant subgraph per task\n\nSee the [manifesto](https://ilo-lang.ai/docs/manifesto/) for full rationale.\n\n## Author\n\nBuilt by [Daniel John Morris](https://danieljohnmorris.com). ilo is the language I wanted while building with LLMs and AI agents.\n",
"bytes": 14922,
"sha": "1c7ac9bf4fbf791bbe6d8345233b25de44d33fd5abd200f247ada24778114588",
"repo_slug": "danieljohnmorris/ilo-lang",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_danieljohnmorris_ilo_lang_ilo_e310610b/readme"
}