agent surface

ilo is built for AI agents.

Every surface is structured. Skills load on demand. Errors carry repair plans. Output contracts are machine-readable from day one.

Get Started GitHub

Modular skills

Eight task-focused modules. Load only what the task needs - typically 1-2 slices. Served by the installed binary via ilo skill get <name>.

skill discovery

ilo skill list                 # name + description per skill
ilo skill list --json          # { schemaVersion: 1, skills: [...] }
ilo skill get ilo-agent        # full content
ilo skill get ilo-errors       # ILO-* codes with fixes

ilo-language ~155 tokens

Writing or reviewing .ilo source: prefix notation, type sigils, guards, match, pipes, records, Result.

ilo-builtins ~120 tokens

Calling builtin functions: list, text, IO, HTTP, JSON, map, math, time, and HOF builtins.

ilo-errors ~115 tokens

Reading ILO-XXXX error codes or fixing failures. Common codes with one-line cause and fix.

ilo-tools ~95 tokens

Declaring and using MCP tools in ilo programs: the tool keyword, HTTP and MCP providers.

ilo-engines ~92 tokens

Choosing between VM, JIT, or AOT execution: feature matrix, defaults, and when each backend matters.

ilo-agent ~90 tokens

Integrating ilo into an agent loop: skill discovery, running programs, and the output contract.

ilo-examples ~75 tokens

Finding a runnable pattern by task shape: curated index of examples/*.ilo.

ilo-edit-loop ~103 tokens

Recovering from failures: the repair cycle, JSON diagnostics, --explain, and fix patterns.

The Claude Code plugin surfaces all eight skills as slash commands. Content is bundled into the binary - no network needed, no drift between spec and runtime.

Diagnostic codes

Every error ilo emits has the shape ILO-<letter><digits>. The letter is the phase namespace. Agents route on prefix without parsing the message.

ILO-L Lexer / tokenisation

ILO-P Parser / syntax

ILO-T Type checker

ILO-R Runtime

fixSafety field

Every diagnostic carries fixSafety: safe (apply without confirmation), likely (apply and note), risky (propose and ask), or manual (surface and stop). Agents never have to guess repair confidence.

Structured repair plans

Diagnostics with mechanical repairs attach a JSON block to ilo check --json output. The plan lists ordered edits. Run ilo --explain ILO-XNNN --json for the per-code contract.

example diagnostic

{
  "code": "ILO-T004",
  "message": "undefined variable 'y'",
  "fixSafety": "likely",
  "repair": [
    {"kind": "rename", "from": "y", "to": "x"}
  ]
}

Full ILO-* catalogue

JSON envelopes

Every ilo subcommand that produces machine-readable output supports --json. New envelopes carry schemaVersion: 1 so agents route on contract, not heuristics.

ilo run --json

{ "ok": value } or { "error": {...} }

ilo check --json

One diagnostic object per error to stdout. Exit 0 on clean.

ilo skill list --json

{ "schemaVersion": 1, "skills": [...] }

ilo version --json

{ "schemaVersion": 1, "version": "...", "features": [...] }

ilo build --json

{ "schemaVersion": 1, "ok": true, "sizeBytes": N }

ilo explain <code> --json

{ "schemaVersion": 1, "code": "ILO-...", "short": "..." }

JSON output contracts are locked by a CI test (tests/json_output_contracts.rs) that exercises each command on a known input and asserts top-level key shape.

Full JSON_OUTPUT.md reference

CLI tools and serv mode

ilo runs programs, composes MCP tools, and stays resident as a JSON-Lines daemon for agent loops that can't afford process-spawn overhead.

ilo serv - JSONL stdio daemon

Long-lived JSON request/response loop on stdin/stdout. Send one object per line, get one back. Zero process-spawn overhead.

# request
{"program":"fn p:n>n;*p 2","func":"fn","args":[21]}

# response
{"ok": 42}

MCP tool surface

Connect any MCP server and call its tools as typed prefix functions. ilo infers signatures and verifies call sites before execution.

# discover tools from an MCP server
ilo tools --mcp m.json --ilo

# run with tools attached
ilo serv --mcp m.json --tools http.json

Installation paths

Pick the path that fits your agent's environment. All produce the same binary with identical output contracts.

Claude Code plugin

Installs ilo, exposes all 8 skills as slash commands. The recommended path for Claude agents.

/plugin marketplace add ilo-lang/ilo

Shell installer

One-liner for macOS and Linux. Pulls the latest release binary.

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

Homebrew

macOS tap. Managed updates via brew upgrade.

brew install ilo-lang/tap/ilo

npm

Node.js environments. Pulls the platform binary on postinstall.

npm install -g ilo-lang

crates.io

Build from source with Cargo. Enables optional Cranelift JIT.

cargo install ilo --features cranelift

ai.txt

Token-minimal whole-spec pointer

A single flat file containing the full ilo spec in the most compressed form possible. Designed to be injected into an LLM context window directly when a specific skill slice isn't appropriate. Think of it as the emergency fallback: if an agent has no skill loaded and needs to understand ilo, ilo spec ai gives them the whole language in one token-efficient hit.

View ai.txt Full spec (llms-full.txt)

serve via CLI

ilo spec ai     # token-minimal ai.txt
ilo spec lang   # full SPEC.md
ilo -ai         # alias for spec ai (back-compat)