rill-ext

rill: Scripting designed for machine-generated code

[!WARNING] This language is experimental. While usable, there may still be some warts and bugs. Breaking changes will occur before stabilization.

The Problem

General-purpose languages weren't designed for machine authorship. They allow null, exceptions, implicit coercion, and ambiguous syntax — and no amount of prompting can structurally prevent an LLM from generating them.

rill makes these failure categories impossible at the language level. No null, no exceptions, no implicit coercion. Variables lock type on first assignment. The $ prefix enables single-pass parsing without a symbol table. Errors halt — control flow is singular and explicit.

The host application controls what capabilities are available. No filesystem, no network, no side effects unless explicitly provided. Zero dependencies. Embeds in Node, Bun, Deno, or the browser.

What This Looks Like

Defensive code you write because the language allows it:

async def classify_and_route(task: str) -> dict:
    # Call LLM — might throw, might return None
    try:
        response = await llm.classify(task)
    except Exception as e:
        return {"error": f"Classification failed: {e}"}

    # Response might be None, might be wrong type
    if response is None:
        return {"error": "No response from classifier"}

    if not isinstance(response.category, str):
        return {"error": f"Expected string, got {type(response.category)}"}

    # Route based on category
    handlers = {
        "billing": handle_billing,
        "technical": handle_technical,
        "general": handle_general,
    }

    handler = handlers.get(response.category, handle_general)

    try:
        result = await handler(task)
    except Exception as e:
        return {"error": f"Handler failed: {e}"}

    if result is None:
        return {"error": "Handler returned None"}

    return result

What's left when the failure modes are structurally impossible:

# No null. No exceptions. No wrong types. If it parses, it's safe to run.

use<ext:app> => $app

$task
  -> $app.classify
  -> .category:string
  -> [
    billing:   $app.handle_billing,
    technical: $app.handle_technical,
    general:   $app.handle_general
  ] ?? $app.handle_general
  -> $($task)

Every defensive check in the Python maps to a failure category rill eliminates:

Why rill?

Four tenets drive every design decision:

Ships with EBNF grammar and LLM reference (with index and progressive fragments). Zero dependencies. Embeds in Node, Bun, Deno, or the browser.

Who Is This For?

Developers building AI agents, copilots, and automation tools who need a scripting runtime that LLMs can generate code for and end users can execute without risk.

rill is not a general-purpose language — it's intentionally constrained. For general application development, use TypeScript, Python, or Go.

rill powers Claude Code Runner, a rich automation tool for Claude Code.

Quick Start

Three entry points, in order of commitment.

1. Easy Button: Generate a Package with Claude Code

rill-make is a Claude Code plugin that authors complete rill packages from a description. Install it from the rcrsr/claude-plugins marketplace:

/plugin marketplace add rcrsr/claude-plugins
/plugin install rill-make@claude-plugins
/reload-plugins

Then run /rill-make:create-rill-package and describe what you want. The skill walks an 8-phase workflow: doc fetch, requirements gathering, clarifying questions, extension identification, data-flow design, custom-extension design, implementation, and validation. It emits a complete rill package with rill-config.json, scripts, and any custom TypeScript extensions. Subagents rill-architect, rill-engineer, and rill-reviewer own design, implementation, and validation.

See the rill-make README for end-to-end usage.

2. CLI: Bootstrap and Run from the Shell

@rcrsr/rill-cli bootstraps, manages, validates, builds, and runs rill packages from the command line.

npm install -g @rcrsr/rill-cli

rill bootstrap                              # initialize project + .rill/npm/
rill install @rcrsr/rill-ext-anthropic      # mount an extension
rill run                                    # execute the project entry

Additional subcommands: rill exec (run a .rill file or stdin), rill eval (evaluate a single expression), rill check (lint and typecheck), rill build (bundle for production), rill describe (print callable contracts as JSON).

See the rill-cli README for the full subcommand reference.

3. Embed: Use @rcrsr/rill Directly

When you need to embed rill inside a Node, Bun, Deno, or browser host, import the runtime and drive it yourself.

import { parse, execute, createRuntimeContext, extResolver } from '@rcrsr/rill';
import { createOpenAIExtension } from '@rcrsr/rill-ext-openai';

const ext = createOpenAIExtension({
  api_key: process.env.OPENAI_API_KEY,
  model: 'gpt-4o',
});

const ctx = createRuntimeContext({
  resolvers: { ext: extResolver },
  configurations: {
    resolvers: {
      ext: { llm: ext.value },
    },
  },
});

const result = await execute(parse(`
  use<ext:llm> => $llm
  $llm.message("Summarize this code for issues")
    -> .content -> .contains("ERROR") ? "Issues found" ! "All clear"
`), ctx);

await ext.dispose?.();

Switch providers by changing one line, createAnthropicExtension or createGeminiExtension. Scripts stay identical. See rill-ext for the full extension catalog.

Extensions

Core extensions ship with @rcrsr/rill: fs, fetch, exec, kv, crypto. Vendor extensions (LLM providers, vector databases, storage backends, MCP) live in rill-ext.

See Bundled Extensions for core extension docs and Developing Extensions to write your own.

Related Repositories

Language Overview

Pattern-Driven Conditionals

Branch based on content patterns. Ideal for parsing LLM output.

use<ext:app> => $app

$app.prompt("analyze code")
  -> .contains("ERROR") ? $app.error() ! $app.process()

Bounded Loops

The do<limit: N> construct option caps loop iterations. seq and fan enforce a built-in 10,000-iteration ceiling. The host stays in control.

# Retry until non-empty, bail after 5 attempts
use<ext:app> => $app

"" -> do<limit: 5> {
  $app.prompt("Generate a summary")
} while ($ == "")

# Bounded iteration
$items -> seq({ "Processing: {$}" -> log })

Parallel Execution

Fan out work concurrently. Results preserve order.

# Parallel fan-out with closure
use<ext:app> => $app

["security", "performance", "style"] -> fan(|aspect| {
  $app.prompt("Review for {$aspect} issues")
})

# Parallel filter with method
["critical bug", "minor note", "critical fix"] -> filter({ .contains("critical") })

Closures

First-class functions with captured environment.

|x| ($x * 2) => $double
[1, 2, 3] -> fan($double)  # [2, 4, 6]
5 -> $double               # 10

Dataflow Syntax

Data flows forward through pipes. Host extensions are hoisted with use<ext:name> => $var, then invoked via dotted access.

use<ext:app> => $app

$app.prompt("analyze this code") -> .trim -> log

String Interpolation

Embed expressions in strings. Triple-quotes for multi-line.

"world" -> "Hello, {$}!" -> log  # Hello, world!

"x + 1" => $code
"""
Analyze: {$code}
Return: PASS or FAIL
"""

Designed for LLM Codegen

These aren't arbitrary constraints — they're guardrails for reliable codegen.

What Our Target Users Say

We asked LLMs to review rill. They had opinions.

"Disciplined to the point of stubbornness, but in a good way. It trades familiarity for predictability." — ChatGPT

"You've basically banned the most common footguns in scripting languages." — Gemini

"It's possibly the first language I've seen where humans are the secondary audience." — Claude

Core Syntax

Use Cases

• User-defined workflows. Let power users script automation without exposing arbitrary code execution.
• Multi-phase pipelines. Chain LLM calls with review gates between each step.
• Parallel agent fan-out. Launch specialist agents concurrently, collect structured results.
• Edit-review loops. Iterate until approval or do<limit: N> max attempts.

See Examples for complete workflow patterns.

Documentation

See docs/index.md for full navigation.

License

MIT