Nexus

Nexus is a language built around one bet. LLMs are good at code you can read on the page, and bad at code that depends on what's off the page.

Implicit control flow, hidden state, and ambient authority are where LLMs go wrong. Human review misses these spots too. Nexus puts each resource, each side effect, and each cap need in the syntax at the use site.

Design thesis

Mainstream languages lean on off-page mechanisms. GC, implicit casts, ambient I/O, exceptions propagating through unmarked call stacks. These are the patterns where LLM-written code goes wrong and where human review fails to catch it.

Nexus flips this around:

Off the page (cut)	On the page (Nexus form)
Implicit resource cleanup (GC)	% linear types — used once
Hidden aliasing	& borrow — a read-only view
Ambient I/O	require { Net } — stated up front
Implicit control transfer (continuations)	try/catch — old-school unwind
Positional arguments	add(a: 1, b: 2) — labels required

Each resource state, each side effect, and each dep on the environment is visible in the source text. Context implies nothing.

Why coeffects, and why not effects

Most of the effect-system literature centers on algebraic effects. A function performs an effect, and a handler picks it up through a delimited continuation. The handler decides whether to resume, restart, or abort the effectful work.

Nexus drops that model. A continuation is the quintessential off-page construct. Control flow turns on which handler happens to be installed at runtime, and the handler's resume-or-not behaviour is invisible at the call site.

Instead, Nexus uses coeffects. The require { ... } clause declares what caps a function needs from its environment, rather than what it does to the environment:

cap Logger do
  fn info(msg: string) -> unit
end

let greet = fn (name: string) -> unit require { Logger, Console } do
  Logger.info(msg: "Greeting " ++ name)
  Console.println(val: "Hello, " ++ name ++ "!")
  return ()
end

Logger.info(...) is a direct call to a statically resolved handler method. It does not suspend into a continuation. The handler is a plain value that implements an interface:

let console_logger = handler Logger require { Console } do
  fn info(msg: string) -> unit do
    Console.println(val: "[INFO] " ++ msg)
    return ()
  end
end

inject supplies handler values to a scope, discharging the corresponding require:

let main = fn () -> unit require { PermConsole } do
  inject stdio.system_handler do
    inject console_logger do
      greet(name: "Nexus User")
    end
  end
  return ()
end

Read this as dep injection rather than algebraic effect handling. There are no continuations, no implicit control transfer, and no hidden resume points. The only builtin effect is Exn (the exception type), handled via the usual try/catch with unwind semantics.

Linear types and borrowing

Resources that have to be released — file handles, server sockets, db connections — are tracked as linear types (%). The compiler enforces once-and-only-once use:

let %h = Fs.open_read(path: path)
let %r = Fs.read(handle: %h)      -- %h consumed here
match %r do
  case { content: c, handle: %h2 } ->  -- %h2 extracted
    Fs.close(handle: %h2)      -- %h2 consumed
end

When you need to read without consuming, borrow the value with &:

let server = Net.listen(addr: addr)
let req = Net.accept(server: &server)  -- borrow: server not consumed
let method = request_method(req: &req)   -- borrow: req not consumed
Net.respond(req: req, ...)         -- req consumed
Net.stop(server: server)         -- server consumed

No garbage collector. No implicit drop. The resource lifecycle is on the page.

Cap-based security

Runtime perms map straight to WASI caps:

let main = fn () -> unit require { PermNet, PermConsole } do
  inject net_mod.system_handler, stdio.system_handler do
    try
      let body = Net.get(url: "https://example.com")
      Console.println(val: body)
    catch e ->
      Console.println(val: "Request failed")
    end
  end
  return ()
end

The require { PermNet, PermConsole } clause is checked at build time and enforced again at the WASI runtime level. Only main declares Perm* permissions; other functions and handlers declare the caps they call (require { Net }), and a handler for each cap must be injected around the call.

Building

The compiler ships as a self-extracting POSIX sh + wasm polyglot. Build it locally:

./bootstrap.sh        # produces ./nexus (polyglot launcher) and ./nexus.wasm
cp nexus ~/.local/bin/   # or anywhere on PATH
mkdir -p ~/.local/share/nexus && cp -R nxlib ~/.local/share/nexus/   # stdlib, found at <bin>/../share/nexus/nxlib

std:* imports read nxlib/stdlib/ from the working directory; when it is absent the launcher falls back to $NEXUS_NXLIB, then <bin>/../share/nexus/nxlib.

To bootstrap and install in one step, use --install [PREFIX] (defaults to /usr/local):

./bootstrap.sh --install             # nexus -> /usr/local/bin, stdlib -> /usr/local/share/nexus/nxlib
./bootstrap.sh --install ~/.local    # nexus -> ~/.local/bin, stdlib -> ~/.local/share/nexus/nxlib

wasmtime must be installed and on PATH. These env vars tune the wasmtime process that runs the compiler itself (not compiled programs):

NEXUS_MAX_WASM_STACK=134217728 nexus build foo.nx -o out.wasm   # 128 MiB stack
NEXUS_WASMTIME_ARGS="--dir=/data" nexus build foo.nx -o out.wasm # extra `wasmtime run` args

The committed nexus.wasm at the repo root is the Stage0 seed of the self-host. Any change under src/** or nxlib/** must regenerate it via ./bootstrap.sh, and the new nexus.wasm must land in the same commit. CI enforces nexus.wasm == stage1.wasm.

Usage

nexus repl                          # interactive REPL
nexus build example.nx              # compile to out.wasm
nexus build example.nx -o main.wasm
nexus typecheck example.nx          # typecheck only
nexus test [path]                   # run the test runner
nexus lsp                           # start Language Server (stdio)
nexus help                          # full subcommand listing

Compiled programs run under wasmtime with the wasm proposals the stdlib uses plus the caps they declare. nexus build --explain-capabilities wasmtime prints the exact command for a program:

wasmtime run -W tail-call=y,exceptions=y,function-references=y,stack-switching=y,threads=y main.wasm
wasmtime run -W tail-call=y,exceptions=y,function-references=y,stack-switching=y,threads=y --dir=. main.wasm   # PermFs
nexus build main.nx -o main.wasm && wasmtime run -W component-model=y,exceptions=y -S http -S inherit-network main.wasm   # PermNet (component only)
nexus build main.nx -o main.wasm && wasmtime run -W component-model=y,component-model-async=y,component-model-async-stackful=y,exceptions=y,tail-call=y,function-references=y,stack-switching=y -S p3=y main.wasm   # async_io / Net coop_handler (add -S http -S inherit-network for Net)

nexus build picks the output target from what the program reaches. A program that uses Net builds as a p2 component. A program that uses std:concurrency/async_io (sleep, clock_handler, force_all) or std:network.coop_handler builds as a p3 component, which exports an async wasi:cli/[email protected]. Those APIs suspend only the calling Coop task, so sleeps and HTTP requests in different tasks overlap. A p3 component needs wasmtime's experimental component-model-async-stackful.

Example

import { Console }, * as stdio from "std:stdio"
import { from_i64 } from "std:str"

let fib = fn (n: i64) -> i64 do
  if n <= 1 then return n end
  return fib(n: n - 1) + fib(n: n - 2)
end

let main = fn () -> unit require { PermConsole } do
  inject stdio.system_handler do
    let v = fib(n: 30)
    Console.println(val: "fib(30) = " ++ from_i64(val: v))
  end
  return ()
end

Examples

The examples folder ships minimal, runnable demos of every language surface. The demos cover linear types and borrowing, mutable references, generics, pattern matching, exceptions, caps and handlers, lazy evaluation, and FFI.

Each file builds on its own with nexus build and runs under wasmtime (wasmtime run -W tail-call=y,exceptions=y,function-references=y,stack-switching=y,threads=y --dir=. out.wasm; examples using Net build as components and run with the component flags above). The README inside that folder gives an indexed listing.

AI coding agent support

Nexus ships a Claude Code skill that teaches coding agents the language syntax, type system, effect system, and stdlib.

npx skills add nexus-llm-lang/Nexus --skill nexus-lang

Once installed, Claude Code activates the skill as soon as it writes or reviews a .nx file.

Documentation

The rendered site lives at https://nexus-llm-lang.github.io/. Its source lives in the nexus-llm-lang/nexus-llm-lang.github.io repo.

Document	Description
Design	Design thesis: literal vs contextual
Syntax	Grammar and EBNF
Types	Type system, linear types, borrowing
Effects	Coeffect system, ports, handlers
Semantics	Evaluation model, entrypoint
CLI	Command-line interface
WASM	WASM compilation and WASI capabilities
FFI	Wasm interop
Stdlib	Standard library
Tools	LSP server, CLI diagnostics, AI coding agent skill

License

MIT