Getting Started

Installation

Koru compiles to Zig, so you'll need Zig installed on your system. Once you have Zig, installing Koru is straightforward:

# Install Koru
curl -fsSL https://koru-lang.org/install.sh | sh

# Or using Nix
nix-shell -p koru

# Verify installation
koru --version

Note: Koru is currently in early development. Installation methods may change.

Hello, World!

Every Koru program starts with a main event. Create a file called hello.kz:

// hello.kz
~event main {}
| done {}

~proc main {
    print("Hello, Koru!")
    return { .done = {} }
}

Compiling and Running

Koru compiles to Zig code, which is then compiled to a native binary:

# Compile to Zig
koru compile hello.kz

# Run the compiled program
./hello

The Koru compiler generates optimized Zig code based on your program's structure. Because compilation happens through Zig's comptime system, all event transformations and optimizations are zero-cost.

Event Basics

In Koru, everything revolves around events. Events declare their inputs and possible outputs:

// Events declare their possible outputs upfront
~event greet { name: []const u8 }
| greeting { message: []const u8 }

// Procs implement the event logic
~proc greet {
    const msg = format("Hello, {s}!", e.name)
    return { .greeting = { .message = msg } }
}

// Invoke and handle the result
~greet(name: "Koru")
| greeting g |> print(g.message)

Notice how the event invocation (~greet) immediately handles the output with a branch handler (| greeting g |>). This is event continuation—you always know what happens next.

Error Handling

Events can have multiple output branches, making error handling explicit and exhaustive. Switch between the Code and Flow tabs to see both the syntax and visual representation:

Unlike exceptions that can be thrown anywhere, Koru events declare all possible outcomes upfront. The compiler ensures you handle every branch—no surprises, no hidden control flow. Click the branch buttons in the Flow tab to explore what happens next.

Understanding the Parts

Next Steps

You've learned the basics of Koru! Here's where to go next: