Skip to main content

Getting Started with AILANG

For AI Agents: Plugin Installation (Recommended)​

AILANG is designed to be used with AI coding agents. The easiest way to get started is via your agent's plugin/extension system:

Claude Code​

/plugin marketplace add sunholo-data/ailang_bootstrap
/plugin install ailang

Gemini CLI​

gemini extensions install https://github.com/sunholo-data/ailang_bootstrap.git

What the Plugin Provides​

  • AILANG binary - Auto-installed for your platform
  • MCP tools - ailang_prompt, ailang_check, ailang_run, ailang_builtins
  • Slash commands - /ailang:prompt, /ailang:new, /ailang:run, /ailang:challenge
  • Teaching prompts - Current syntax rules loaded automatically
  • Coding challenges - Learn AILANG by building real programs
  • Full stdlib docs - ailang builtins list --verbose --by-module

See ailang_bootstrap for source code and detailed setup.

Using AILANG with Your Agent​

Once the plugin is installed, ask your agent:

Write an AILANG program that reads a file and counts the lines.

The agent will:

  1. Load the teaching prompt via ailang prompt
  2. Check stdlib functions via ailang builtins list --verbose
  3. Write correct AILANG code
  4. Type-check with ailang check
  5. Run with ailang run --caps IO,FS --entry main

Manual Installation​

For standalone CLI usage or if you prefer manual installation:

# macOS (Apple Silicon)
curl -L https://github.com/sunholo-data/ailang/releases/latest/download/ailang-darwin-arm64.tar.gz | tar -xz
sudo mv ailang /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/sunholo-data/ailang/releases/latest/download/ailang-darwin-amd64.tar.gz | tar -xz
sudo mv ailang /usr/local/bin/

# Linux
curl -L https://github.com/sunholo-data/ailang/releases/latest/download/ailang-linux-amd64.tar.gz | tar -xz
sudo mv ailang /usr/local/bin/

# Verify
ailang --version

MCP Server (Custom Integrations)​

For integrating AILANG tools into AI systems via Model Context Protocol:

# Clone and setup
git clone https://github.com/sunholo-data/ailang_bootstrap.git
cd ailang_bootstrap/mcp-server
npm install
npm start

Configure in your MCP client:

{
  "mcpServers": {
    "ailang-tools": {
      "command": "node",
      "args": ["/path/to/ailang_bootstrap/mcp-server/server.js"]
    }
  }
}

Available Tools:

  • ailang_prompt - Teaching prompt (SOURCE OF TRUTH for syntax)
  • ailang_check - Type-check files
  • ailang_run - Run with capabilities
  • ailang_builtins - Full stdlib documentation
  • ailang_eval - REPL evaluation

For AI Agents: CLI Integration​

If you installed manually, integrate AILANG into your AI coding agent:

Step 2: Get the AILANG Teaching Prompt​

Use the CLI to get the current syntax guide for your AI agent:

# Display the active teaching prompt
ailang prompt

# Save to a file
ailang prompt > ailang-syntax.md

# List all available versions
ailang prompt --list

This prompt teaches AI models:

  • Correct AILANG syntax (not Python/Rust/JavaScript)
  • Pure functional programming with recursion
  • Module system with effects (IO, FS, Clock, Net)
  • Record updates, pattern matching, ADTs
  • Auto-imported std/prelude (no manual imports for comparisons)

Include the prompt output in your AI agent's system prompt or context. You can also browse prompts on the website.

Step 3: Test AI Code Generation​

Ask your AI agent to write AILANG code:

Using AILANG, write a program that reads a file and counts the number of lines.

[Paste output from: ailang prompt]

Expected output:

module benchmark/solution

import std/io (println)
import std/fs (readFile)

export func countLines(content: string) -> int {
  -- Implementation using recursion
  ...
}

export func main() -> () ! {IO, FS} {
  let content = readFile("data.txt");
  println("Lines: " ++ show(countLines(content)))
}

Step 4: Run AI-Generated Code​

ailang run --caps IO,FS --entry main solution.ail

AI Success Metrics​

Latest benchmark results:

  • Check Benchmark Dashboard for current metrics
  • Best model: Claude Sonnet 4.5 (consistently highest success rates)
  • Results updated after each release

See AI Prompt Guide for detailed instructions.

For Human Developers: Manual Installation​

Installation Options​

Download pre-built binaries from the latest release.

From Source (For Development)​

git clone https://github.com/sunholo/ailang.git
cd ailang
make install
ailang --version

Add Go bin to PATH:

# For zsh (macOS default)
echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Development workflow:

make quick-install    # Fast rebuild after changes
make test            # Run tests
make verify-examples # Test example files

Quick Start​

Hello World​

examples/runnable/hello.ail
-- hello.ail - Simple hello world program
module examples/runnable/hello

import std/io (print)

-- Entry module with exported main function
export func main() -> () ! {IO} =
  print("Hello, AILANG!")

Run it:

ailang run --caps IO examples/runnable/hello.ail

Note: Flags must come BEFORE the filename when using ailang run.

Working with Values​

examples/runnable/values_basic.ail
-- values_basic.ail - Working with values and string concatenation
-- Used in: docs/docs/guides/getting-started.mdx
module examples/runnable/values_basic

-- Entry module with exported main function
-- Gets print prelude automatically (no import needed)
export func main() -> () ! {IO} =
  let name = "AILANG" in
  let version = 0.6 in
  println("Welcome to " ++ name ++ " v" ++ show(version))

Run it:

ailang run --caps IO examples/runnable/values_basic.ail

Lambda Expressions​

examples/docs/lambdas_full.ail
-- lambdas_full.ail - Lambda expressions and higher-order functions
-- Used in: docs/docs/guides/quick-start-examples.mdx
module examples/docs/lambdas_full

import std/io (println)

export func main() -> () ! {IO} = {
  -- Basic lambda
  let double = \x. x * 2;
  println("double(5) = " ++ show(double(5)));

  -- Multi-parameter lambda (curried)
  let add = \x. \y. x + y;
  println("add(3)(4) = " ++ show(add(3)(4)));

  -- Partial application
  let add10 = add(10);
  println("add10(5) = " ++ show(add10(5)));

  -- Function composition
  let compose = \f. \g. \x. f(g(x));
  let inc = \x. x + 1;
  let doubleThenInc = compose(inc)(double);
  println("doubleThenInc(5) = " ++ show(doubleThenInc(5)))
}

Run it:

ailang run --caps IO examples/docs/lambdas_full.ail

Using the REPL​

Start the interactive REPL:

ailang repl

Try some expressions:

λ> 1 + 2
3 :: Int

λ> "Hello " ++ "World"
Hello World :: String

λ> let double = \x. x * 2 in double(21)
42 :: Int

λ> :type \x. x + x
\x. x + x :: ∀α. Num α ⇒ α → α

λ> :quit

Testing Your Code​

NEW in v0.4.5: AILANG now supports inline tests for pure functions!

Writing Inline Tests​

Add tests directly to your function definitions:

examples/runnable/recursion_factorial.ail
-- recursion_factorial.ail
-- Demonstrates simple recursive function with LetRec
-- Status: ✅ Working (M-R4 recursion support)

module examples/runnable/recursion_factorial

import std/io (println)

-- Classic factorial using recursion
pure func factorial(n: int) -> int
  tests [
    (0, 1),
    (1, 1),
    (5, 120),
    (10, 3628800),
    (12, 479001600)
  ]
{
  if n <= 1 then 1 else n * factorial(n - 1)
}

-- Tail-recursive factorial with accumulator
pure func factorialTail(n: int, acc: int) -> int
  tests [
    ((0, 1), 1),
    ((1, 1), 1),
    ((5, 1), 120),
    ((10, 1), 3628800),
    ((12, 1), 479001600)
  ]
{
  if n <= 1 then acc else factorialTail(n - 1, n * acc)
}

export func main() -> () ! {IO} {
  let result1 = factorial(5);
  let result2 = factorialTail(10, 1);

  println("factorial(5) = " ++ show(result1));
  println("factorialTail(10, 1) = " ++ show(result2))
}

Note the test syntax:

  • Single-parameter functions: tests [(input, expected), ...]
  • Multi-parameter functions: tests [((arg1, arg2), expected), ...]

Running Tests​

ailang test examples/runnable/recursion_factorial.ail

Output:

→ Running tests in examples/runnable/recursion_factorial.ail

Test Results
Module: All Tests

Tests:
  ✓ factorial_test_1 (1.5ms)
  ✓ factorial_test_2 (800µs)
  ✓ factorial_test_3 (1.2ms)
  ✓ factorial_test_4 (900µs)

────────────────────────────────────────────
✓ All tests passed!

4 tests: 4 passed, 0 failed, 0 skipped (4.4ms)

Key features:

  • Tests run automatically on every test invocation
  • Fast execution (~10-60ms per file)
  • Works alongside export func main() - no conflicts!
  • Supports all data types: int, float, bool, string, lists, tuples

Limitations:

  • Only works for self-contained pure functions
  • Functions calling other user-defined functions not yet supported
  • Effect mocking not yet supported

See the Language Reference for complete documentation.

Working Examples​

The following examples are confirmed to work with the current implementation:

Recursion:

  • examples/recursion_factorial.ail - Recursive factorial function
  • examples/recursion_fibonacci.ail - Fibonacci sequence
  • examples/recursion_quicksort.ail - Quicksort implementation
  • examples/recursion_mutual.ail - Mutual recursion (isEven/isOdd)

Records:

  • examples/micro_record_person.ail - Record literals and field access
  • examples/test_record_subsumption.ail - Record subsumption

Effects:

  • examples/test_effect_io.ail - IO effect examples
  • examples/test_effect_fs.ail - File system operations
  • examples/micro_clock_measure.ail - Clock effect (time, sleep)
  • examples/micro_net_fetch.ail - Net effect (HTTP GET)

Pattern Matching & ADTs:

  • examples/adt_simple.ail - Algebraic data types
  • examples/adt_option.ail - Option type with pattern matching
  • examples/guards_basic.ail - Pattern guards

Blocks:

  • examples/micro_block_if.ail - Block expressions with if
  • examples/micro_block_seq.ail - Sequential blocks
  • examples/block_recursion.ail - Recursion in blocks

See examples/STATUS.md for the complete list of 48+ working examples.

For Beginners​

  1. Introduction - Understand what AILANG is
  2. Examples - See working code in action
  3. Playground - Try code in your browser
  4. Language Reference - Complete syntax guide

For AI Agents​

  1. Teaching Prompt - Syntax rules for AI models
  2. AI Integration Guide - Best practices
  3. Examples - Patterns to learn from

For Troubleshooting​

Next Steps​

See Also​