KARN — The Agent's Language

A token-minimal, platform-agnostic programming language built for AI agents.

4x denser than Python. 3 execution modes. 3 codegen targets. Every ecosystem.

@web  #http #db.pg #auth

type User:{id:N, name:S, role:S}

^getUser->req:
  tok  = auth.verify(req.header.token)?
  user = db.q("users", {id:req.p.id})?
  !user

http.serve(3000, {"/users/:id": getUser})

Why KARN for AI Agents

• Token economy — 76% fewer tokens than Python for equivalent logic. More code fits in your output limit.
• Context window efficiency — Smaller source = more of the program fits in context. You reason about the whole thing.
• Deterministic semantics — No exceptions, no hidden control flow. Every I/O returns Ok|Err. You always know what executes.
• Multi-platform, one source — Generate once. Compile to C (native), JS (Node.js), HTML (browser), or Python.
• Full ecosystem access — from pip numpy, from npm react, from cargo serde. One line.

Quick Start

Install

git clone https://github.com/karn-lang/karn.git
cd karn
pip install -e .

Hello World

echo '! "Hello from KARN"' > hello.kn
karn run hello.kn

Run Examples

karn run examples/hello.kn
karn run examples/fibonacci.kn        # → 55
karn run examples/collections.kn      # → 42

REPL

karn repl

Type Check

karn check examples/*.kn

Compile

karn build hello.kn --target c        # → hello.c
karn build hello.kn --target js       # → hello.js
karn build hello.kn --target web      # → hello.html
karn build hello.kn --target python   # → hello.python.py
karn build hello.kn --target macos-arm64  # → hello (native binary)
karn build hello.kn --target linux-x64    # → hello (ELF binary)

Language Reference

Variables

x = 42              -- immutable bind
~count = 0           -- mutable bind
name:S = "karn"      -- typed bind
const PI:N = 3.14    -- constant

Functions

add->a:N b:N:N       -- function with types
  a + b

^export->x:           -- exported (public)
  !x * 2

square = x -> x * x  -- lambda

Types

type User:{id:N, name:S, email:S?}
type Tree<T>:{val:T, kids:[Tree<T>]}
type Result<T>:{Ok:T | Err:S}

Error Handling

data = http.get(url)?           -- propagate error up
val  = cache.get(key)??fallback -- fallback on error

Concurrency

[a, b, c] = taskA() & taskB() & taskC()  -- parallel
auth.verify(tok) |> db.q("users")         -- sequential pipe
result = primary()|~fallback()             -- race
data = http.get(url).retry(3).t(5000)?    -- retry + timeout

Collections

doubled = items*(x -> x * 2)   -- map
actives = users%(u -> u.active) -- filter
sequence = 1..10               -- range

Pattern Matching

match result{
  Ok(v)  -> !v
  Err(e) -> log.err(e) |> !nil
}

Interop

from pip numpy as np
from npm react as R
from cargo serde as serde
from sys ffmpeg as ff

Execution Modes

| Mode | Command | Use Case | |------|---------|----------| | Interpreted | karn run script.kn | Instant iteration, REPL | | JIT | karn run --jit server.kn | Warm services, ML loops | | Compiled | karn build app.kn --target c | Production deployment |

Codegen Targets

| Target | Output | How | |--------|--------|-----| | C | .c source | gcc -o output input.c -lm | | JavaScript | .js | node output.js | | Web | .html | Open in browser | | Python | .python.py | python output.python.py | | macOS ARM | native binary | Auto-compiled with gcc | | Linux x64 | native binary | Auto-compiled with gcc | | WASM | .wasm | emcc or clang --target=wasm32 |

Comparison

| | KARN | Python | Rust | TypeScript | |---|---|---|---|---| | Token density | ~2.1/LOC | ~6.8/LOC | ~11.5/LOC | ~9.2/LOC | | Platform targets | All | Server | Native+WASM | Web+Node | | Error handling | Result+chain | Exceptions | Result | Mixed | | Async model | Default, 1 op | async/await | Tokio | async/await | | Ecosystem | pip+npm+cargo+sys | pip native | cargo+C FFI | npm native |

Project Structure

karn-lang/
├── files/karn.py          # Runtime: lexer, parser, interpreter, codegen, REPL
├── index.html             # Landing page
├── docs.html              # AI Agent Documentation
├── karn-spec.json         # Machine-readable language spec
├── examples/              # .kn example programs
├── tests/                 # Test suite (91 tests)
├── pyproject.toml         # Package config
└── README.md

For AI Agents

• Agent Docs: docs.html — Complete spec written for agents, not humans
• Machine-readable spec: karn-spec.json — Parseable JSON with full language definition
• Token savings: 76% vs Python, 83% vs TypeScript, 89% vs Rust

License

MIT